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About This Book 


This book contains the information you need to install and use the IBM® PowerPC 405GP Reference 
Design Kit, a hardware and software development tool for the PowerPC PPC405GP 32-bit RISC 
microprocessor. 


The PowerPC 405GP Reference Design Kit (hereinafter referred to as the PPC405GP design kit) 
hardware includes the PowerPC 405 Reference Board (hereinafter referred to as the reference 
board), power supply, and board interface cables. The board and power supply are housed in an ATX 
form factor case. Features of the reference board include a PowerPC PPC405GP processor, 16MB 
SDRAM, four 32-bit PCI slots, built-in Ethernet support, 512KB socketed flash memory, 512KB 
SRAM, 2 serial ports, a time-of-day clock with 8KB NVRAM, an IR controller, and a mouse/keyboard 
controller. 


The PPC405GP design kit software includes the ROM Monitor (resident in the flash memory on the 
board), ROM Monitor source code, IBM’s OS Open real time operating system, sample application 
programs, application development libraries and tools, IBM’s High C/C++ compiler, and IBM’s 
RISCWatch, a source-level debugger that runs on the host system. 


The PPC405GP design kit also includes technical specifications and board schematics. 


Connection of the reference board to a host system is required for the exercises in this book. 
Supported host systems include: 


¢ An IBM or compatible PC running one of the following: 


— Windows 95/98 
— Windows NT 4.0 


¢ A Sun SPARCstation 5, 10, or 20 workstation running one of the following: 


— Solaris 2.4 (or higher) 
— SunOS 4.1.3 (or higher) 


« An IBM RISC System/6000™ workstation running AIX™ 4.1 (or higher) 


Who Should Use This Book 


This book is for hardware and software developers who need to evaluate the PowerPC PPC405GP 
microprocessor and use the debugging features of the PowerPC 405GP Reference Design Kit to 
support software development. 


Users should understand hardware and software development tools, concepts, and environments. 
Specifically, users should understand: 


* The host's operating system 


¢ The PowerPC Architecture™ and implementation-specific characteristics of the PowerPC 
microprocessor being used 


* Cand Assembler language programming 
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How to Use This Book 
This book contains the following chapters and appendixes: 


Chapter 1, “Overview of the Reference Design Kit” describes the product, its hardware and software 
components, and its relationship with the software tools on the host. 


Chapter 2, “Host System Requirements’ lists the hardware and software requirements of the host 
system. 


Chapter 3, “Installing the Software” describes the software installation on the host system. 


Chapter 4, “Host Configuration” describes the steps required to facilitate communications between 
the host computer and the reference board. 


Chapter 5, “Hardware” describes the reference board, its memory map, its hardware components and 
their functions. 


Chapter 6, “Board Connectors” describes the reference board connectors and the procedures for 
connecting the board to a host system. 


Chapter 7, “ROM Monitor” describes the operations of the ROM monitor. 


Chapter 8, “Sample Applications” describes how to compile, load, and run the sample applications on 
the reference board. 


Chapter 9, “Application Libraries and Tools” describes the application libraries and host tools provided 
with the reference board software. 


Chapter 10, “OS Open Function Reference” lists the OS Open functions for the PowerPC 405 
Reference Board platform. The function calls are arranged alphabetically by function name. 


Appendix A, “Program Trace Calls” describes the messages for interfacing a debugger on the host 
system to the ROM Monitor on the reference board. 


Appendix B, “ROM Monitor Load Format” describes the load format requirements supported by the 
ROM monitor. 


Conventions Used in This Book 


This book follows the numeric and highlighting notation conventions based on those used in the RISC 
System/6000 and AIX publications. 


Numeric Conventions 


In general, numbers are used exactly as shown. Unless noted otherwise, all numbers are in decimal, 
and, if entered as part of a command, are entered without format information. 


In text, binary numbers are preceded by a “B” followed by the number enclosed in single quotes, for 
example: 


B'010' 


In commands, binary numbers are preceded by “Ob” or “b” followed by the number, which may be 
enclosed in single quotes, for example: 


0b010 or b'010’ 
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In text, hexadecimal numbers are preceded by an “X” followed by the number enclosed in single 
quotes, for example: 


X'1A7' 

In commands, hexadecimal numbers are preceded by “Ox” or “x” followed by the number, which may 
be enclosed in single quotes, for example: 

Ox1a7 or x'1a7' 

In text, the hexadecimal digits A through F appear in uppercase. In commands, these digits are 
typically entered in lowercase. 


Highlighting Conventions 
This book uses the following highlighting conventions: 


The names of invariant objects known to the software appear in bold type. In some text, however, 
such as in lists, no special typographic treatment is used. Examples of such objects include: 


¢ Function and macro names 
¢ Data types and structures 
¢ Constants and flags 


Names of objects known to the software must be entered exactly as shown. 


¢ Variable names supplied by user programs appear in italic type. In some text, however, such as in 
lists, no special typographic treatment is used. Examples of these objects include arguments and 
other parameters. 


¢ No highlighting appears in code examples. 


Syntax Diagram Conventions 


Throughout this book, diagrams illustrate the syntax for string formats and commands. The following 
list shows how to read these diagrams: 


¢ Read the syntax diagrams from left to right, from top to bottom, following the path of the line. 
¢ At»-— symbol begins a diagram. 

* A——® symbol indicates continuation of a diagram on the next line. 

¢« A »—— symbol indicates continuation of a diagram from the previous line. 

° A—< symbol terminates a diagram. 


* Keywords are in regular type, and variables are in italics. Keywords must be typed exactly as 
shown. 


* Keywords or variables on the main path of a diagram are required. 


=—— keyword — variable! — variable2 ————_______»>~< 


¢ Keywords or variables shown on branches below the main path are optional. 


»>»>— keyword ioe ii aweet: ss 
variable 1 i variable2 
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¢ Keywords or variables can appear in a stack, indicating that only one item in a stack can be 
chosen. If an item in a stack is on the main path, you must choose an item from the stack. If all 


items in a stack are below the main path, you may choose an item from the stack. 


For example, in the following syntax diagram, you must choose either variable1 or variable2. 
However, because variable3 and variable4 are below the main path, neither is required. 


>>— keyword variable 1 
ull variable2 ] variable3 
variable4 


¢ A repeat separator is a returning arrow that surrounds a syntax element or group and shows that 


the element or group can be repeated. 


ee 


Contacting the IBM Embedded Systems Solution Center 


For information about the PowerPC 405GP Reference Design Kit and the IBM family of hardware and 
software products for embedded system developers, call the IBM Embedded Systems Solution 


Center at (919) 543-5701, or check out the IBM Microelectronics web site at: 


http://www.chips.ibm.com/products/embedded 


Please send any comments or questions regarding this product to the following Internet address: 


ppcsupp@us.ibm.com 


Related Publications 


Many of the following publications are included on the CD ROM that comes with the evaluation kit. 


The others are available from your IBM Microelectronics representative: 
¢ Embedded Application Binary Interface (EABI) Publications 
PowerPC Embedded Application Binary Interface (EABI) 
System V Application Binary Interface, Third Edition, 0-13-0100439-5 
System V Application Binary Interface, PowerPC Processor Supplement 
¢ IBM High C/C++ Publications 
The following list includes the books in the IBM High C/C++ library: 
IBM High C/C++ Programmer's Guide for PowerPC, 92G6920 
IBM High C/C++ Language Reference for PowerPC, 92G6923 
IBM ELF Assembler User’s Guide for PowerPC, 92G6921 
IBM ELF Linker User's Guide for PowerPC, 92G6922 
* OS Open Publications 
IBM OS Open Programmer's Reference, Volume 1, 92G6911 
IBM OS Open Programmer's Reference, Volume 2, 92G6912 
IBM OS Open User's Guide, 92G6897 
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¢« RlSCWatch Debugger Publications 
RISCWatch Debugger User’s Guide, 13H6964 
RISCWatch Debugger Installation Guide, 13H6984 
* PowerPC PPC405GP User’s Manual 
PowerPC 405GP RISC Microprocessor User’s Manual, 
¢ Reference Board Publications 
PowerPC 405 Reference Board Manual 
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Chapter 1. Overview of the Reference Design Kit 


This chapter introduces the hardware and software components included in the PPC405GP design 
kit. 


1.1. Hardware Components 


The PPC405GP design kit contains the reference board, power supply line cord, serial port and 
Ethernet cables. 


1.1.1. Reference Platform 


The reference board and power supply are housed in an ATX form factor case. Features of the 
reference board include the PowerPC PPC405GP processor, 16MB SDRAM, four 32-bit PCI slots, 
built-in Ethernet support (10BaseT/100BaseTX), 512KB socketed flash memory, 512KB SRAM, 2 
serial ports, a time-of-day clock with 8KB NVRAM, °C port, IR port, and a mouse/keyboard controller. 
A PCI VGA display adapter is also included in the kit. 


For a detailed description of the reference board, refer to the PowerPC 405 Reference Board Manual. 


1.1.2 Cables and Power Supply 


The PPC405GP design kit includes a serial port interface cable for connecting the board’s serial port 
1 to a terminal or terminal emulator running on the host. The Sun version of the kit also contains a 
male-to-male adapter to support this connection. 


An Ethernet crossover cable is provided in the kit to support direct Ethernet communication with the 

host system. A standard 10BaseT/100BaseTX RJ45 Ethernet connector is provided on the reference 
board. The Ethernet crossover cable is for direct connection to a single host and cannotbe used with 
a hub or a building’s Ethernet network. The crossover cable is only supported for 10Mb/s operation - 
for 100Mb/s a hub (not supplied) should be used. 


A power supply line cord is also provided with the PPC405GP design kit. 


1.2 Software Components 


The PPC405GP design kit software consists of the Board Support Package (BSP), the RISCWatch 
source level debugger, and the IBM High C/C++ evaluation compiler. 


1.2.1 BSP Software 


The BSP software includes the ROM Monitor code resident in flash memory, ROM Monitor source 
code, the IBM OS Open real time operating system, several sample programs (including the 
Dhrystone benchmark program), and application development libraries and tools. 
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1.2.1.1 ROM Monitor 


The ROM Monitor program for the reference board is supplied in the 512KB socketed flash memory 
module on the reference board. This code initializes the 405GP processor and the board for serial 
and Ethernet communications. By supporting communications with the host computer system, the 
ROM Monitor allows applications to be loaded from the host onto the board and debugged using the 
RISCWatch source level debugger in ROM Monitor mode. 


The ROM Monitor is accessed through a terminal (or terminal emulator) attached to serial port 1 on 
the board. The RISCWatch debugger, when in ROM Monitor mode, runs on the host system, 
communicating with the ROM Monitor through serial port 2 or the Ethernet interface on the board. 


The ROM Monitor source code is provided and can be readily used for product development. The 
availability of the code helps lower software development costs and quicken product time to market. 
The code is also provided so that debuggers other than RISCWatch may be integrated with the 
PPC405GP design kit. Appendix A describes the trace calls that support communication between the 
RISCWatch debugger on the host and the ROM Monitor running on the board. 


1.2.1.2 OS Open Real-Time Operating System 


OS Open is a real-time operating system (RTOS) available for the PowerPC 400, 600, and 700 
families of processors. OS Open is designed to take full advantage of the power of the IBM PowerPC 
RISC processors. Also, because the OS Open environment is built in a scalable fashion, it can be 
configured to meet the functional requirements and memory constraints of a wide variety of 
embedded systems. 


OS Open features: 
¢ Hard real-time support, including deterministic execution, priority inheritance protocols, and priority 


ceiling protocols 
¢ Board support packages for plug-and-play operation of popular board-level products 


¢ Support for existing American National Standards Institute (ANSI) C and emerging POSIX 
standards 

* Open network interfaces to support embedded systems in heterogeneous environments 

* Scalable implementations to meet the requirements and constraints of a variety of embedded 
systems 


The version of OS Open included in the BSP software contains a reduced-function kernel that limits 
the number of threads that can be in existence at one time. Additional details can be found in the 
README file following software installation. A full-function OS Open kernel is available from IBM. 
Contact the IBM Embedded Systems Solutions Center at (919) 543-5701 for additional information. 


1.2.1.3. Dhrystone Benchmark Program 


The Dhrystone benchmark is a commonly available integer benchmark. It is included as an example 
program to be built, loaded onto the board, and executed. The results of this benchmark may vary 
based on compiler options and the system environment in which it is run. 


1.2.1.4 Application Tools 


Several host-based tools are provided to support ROM and application development on the reference 
board. 
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1.2.2 RISCWatch Debugger 


The RISCWatch source level debugger provides a window-based debugging environment for loading, 
debugging, and executing application programs on the board. Debugger installation and usage for 
ROM Monitor and OS Open (non-JTAG) targets are addressed in the RISCWatch Debugger 
Installation Guide and the RISC Watch Debugger User's Guide included on the publications CD-ROM 
in the kit. A sample debug session is included with the debugger. 


1.2.3. IBM High C/C++ Evaluation Compiler 


The IBM High C/C++ compiler is a globally optimizing compiler developed for the PowerPC family of 
processors. It produces executable code in Extended Link Format (ELF) file format. The version 
included in the kit is a limited capacity version created specifically for the PPC405GP design kit. It 
supports the compilation, assembly, and linkage of the sample application programs and the ROM 
Monitor source code. A full featured version of the IBM High C/C++ compiler is available from IBM. 
For more information call the PowerPC Embedded Systems Solutions Center at (919) 543-5701. 
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Chapter 2. Host System Requirements 


This chapter describes the hardware and software requirements of the host system to which the 
reference board is to be connected. Supported host systems include: 


¢ IBM (or compatible) PC running one of the following: 


— Windows 95/98 
— Windows NT 4.0 


¢ Sun SPARCstation 5, 10, or 20 workstation running one of the following: 


— Solaris 2.4 (or higher) 
— SunOS 4.1.3 (or higher) 


¢ IBM RS/6000 workstation running AIX 4.1 (or higher) 


2.1 PC Host System Requirements 


Hardware requirements of the host PC include: 
¢ IBM or compatible system unit. Minimum requirements: x486 DX2 50/66 MHz with 8MB of RAM 


¢« VGA/SVGA Display Monitor. Minimum requirement: VGA 640 x 480. Recommended: SVGA 1024 x 
768 


¢ Approximately 30MB of free disk space. This space is required for the IBM High C/C++ compiler, 
the Board Support Package software, and the RISCWatch debugger. When planning disk space 
usage, consider disk space requirements for Windows and any other software packages. 


¢ Atleast one available serial port for terminal emulation. A second serial port is required if a SLIP 
host-to-board connection is to be used instead of an Ethernet connection. For performance 
reasons, an Ethernet connection is strongly recommended. Establishing an Ethernet host-to-board 
connection will most likely require the installation of an Ethernet adapter card on the host (if not 
already installed) and some additional connectivity hardware. That hardware might include any or 
all of the following: 


— An Ethernet 10BaseT/100BaseTX network transceiver, a twisted pair cable, and a hub. Ata 
minimum, a point-to-point connection will require the Ethernet crossover cable supplied with the 
kit. The Ethernet crossover cable is for direct connection to a single host and cannot be used 
with a hub or a building’s Ethernet network. The crossover cable is only supported for 10Mb/s 
operation - for 100Mb/s a hub (not supplied) should be used. 


The following software must be installed on the host PC to run the debugger that communicates with 
the ROM Monitor on the board: 

« RlSCWatch 4.0 or higher 

* Windows 95/98 or Windows NT 4.0 

Windows users who want to establish a SLIP host-to-board connection over a second serial port, 
require additional software since the TCP/IP package that comes with Windows does not support 


SLIP communications. One TCP/IP package that can be used for Windows SLIP communications is 
Trumpet Winsock, a TCP/IP protocol stack available from the www.trumpet.com Internet site. 
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Appropriate installation documentation can be found at the Trumpet site. Users should refer to the 
documentation for the terms and conditions of using Trumpet Winsock. Information regarding the 
setup and use of Trumpet Winsock can be found in Chapter 4, “Host Configuration.” 


Note: Trumpet is not recommended for Windows users already connected to a network since 
installing Trumpet may cause problems with previously defined networks. If the recommended 
Ethernet host-to-board connection is going to be used (instead of the SLIP host-to-board 
connection), Windows users need not install Trumpet since the TCP/IP package that comes 
with Windows can be used to establish the Ethernet connection. 


2.2 SUN Host System Requirements 


Hardware requirements of the host Sun workstation include: 


¢ Approximately 30MB of free disk space. This space is required for the IBM High C/C++ compiler, 
the Board Support Package software, and the RISCWatch debugger. When planning disk space 
usage, consider disk space requirements for the operating system and any other software 
packages. 


¢ An available serial port for terminal emulation and an Ethernet Attachment Unit Interface (AUI) or 
RJ-45 port for host-to-board communications. Most Sun SPARCstations come equipped with one 
serial port and an Ethernet AUI port. Consult your Sun literature for additional details. 


¢ Any or all of the following hardware to establish an Ethernet connection between the board and the 
host. 


— An Ethernet 10BaseT/100BaseTX network transceiver, a twisted pair cable, and a hub. Ata 
minimum, a point-to-point connection will require the Ethernet crossover cable supplied with the 
kit. The Ethernet crossover cable is for direct connection to a single host and cannot be used 
with a hub or a building’s Ethernet network. The crossover cable is only supported for 10Mb/s 
operation - for 100Mb/s a hub (not supplied) should be used. 


¢ Agraphics display to display debugger screens 


The following software must be installed on the Sun workstation to run the debugger that 
communicates with the ROM Monitor on the board: 

« RlSCWatch 4.0 or higher 

* SunOS 4.1.3 (or higher) or Solaris 2.4 (or higher) 

¢ A window system such as Open Windows or CDE 

¢ Motif 1.2 (Solaris) 


2.3. RS/6000 Host System Requirements 


Hardware requirements of the host RS/6000 computer include: 


¢ Approximately 30MB of free disk space. This space is required for the IBM High C/C++ compiler, 
the Board Support Package software, and the RISCWatch debugger. When planning disk space 
usage, consider disk space requirements for the operating system and any other software 
packages. 
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¢ Atleast one available serial port for terminal emulation. A second serial port is required if a SLIP 
host-to-board connection is to be used instead of an Ethernet connection. For performance 
reasons, an Ethernet connection is strongly recommended. Most RS/6000 computers come 
equipped with two serial ports and an Ethernet adapter. Please consult your RS/6000 literature for 
more details. Establishing an Ethernet host-to-board connection may require additional 
connectivity hardware. That hardware might include any or all of the following: 


— An Ethernet 10BaseT/100BaseTX network transceiver, a twisted pair cable, and a hub. Ata 
minimum, a point-to-point connection will require the Ethernet crossover cable supplied with the 
kit. The Ethernet crossover cable is for direct connection to a single host and cannot be used 
with a hub or a building’s Ethernet network. The crossover cable is only supported for 10Mb/s 
operation - for 100Mb/s a hub (not supplied) should be used. 


¢ Atleast one available serial port for terminal emulation. A second serial port is required if a SLIP 
host-to-board connection is to be used instead of an Ethernet connection. For performance 
reasons, an Ethernet connection is strongly recommended. Most RS/6000 computers come 
equipped with two serial ports and an Ethernet adapter. Please consult your RS/6000 literature for 
more details. 


¢ Agraphics display (IBM 6091 or similar), to display debugger screens 


The following software must be installed on the host RS/6000 computer to run the debugger that 
communicates with the ROM Monitor on the board: 


¢« RlSCWatch 4.0 or higher 
¢ AIX Version 4.1 or higher 
¢ AlX/Windows™ with X11R5 and Motif 1.2 
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Chapter 3. Installing the Software 


This chapter describes the procedures for installing the BSP software and the High C/C++ Compiler 


on the host system. Details of the software, its directories and their contents, are also given. 
Instructions for installing the RISCWatch Debugger software can be found in the RISCWatch 
Debugger Installation Guide. Please refer to the section corresponding to your host system. 


3.1. PC Software Installation 


3.1.1. BSP Software Installation - PC 
Before beginning the installation, you must have: 


¢ BSP for PC installation diskettes 
¢ APC running Windows 95/98 or Windows NT 4.0 


The following procedure installs the BSP software: 


Note: For Windows NT users, we recommend that you log on as administrator. 


1. Insert the installation diskette labeled “BSP - PC” and “1 of n” (n may vary) into diskette drive A:. 


2. Select Start from the Windows task bar. 

3. Select Run. 

4. Type a:setup then press Enter to run the installation program. 
5. Follow the installation program instructions. 


If the default install directory is accepted, the BSP software is installed in the \osopen directory 
tree. The \osopen directory tree contains the files and tools that support OS Open application and 
ROM development. The \osopen subdirectories and their contents are as follows. 

\bin 

This directory contains several host based utilities used for application and ROM program 
development. 

¢ elf2rom.exe - creates a ROM image from an ELF executable file 

¢ eimgbld.exe - creates a ROM Monitor loadable image from an ELF executable file 

¢ hbranch.exe - places an absolute branch in the last address of a ROM image 


* rambuild.exe - creates an assembler source file that contains the files found in a specified 
directory 


* make.exe - supports the use of makefiles when building application programs 
* bootpd.exe - bootp server to support ROM Monitor downloads 
* tftpd.exe - tftp server to support host-to-board file transfers 


\examples 


This directory contains example OS Open programs. 
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\m405_evb 


This directory contains the ROM Monitor and OS Open platform specific code for the reference board 
included in the kit. 

¢ README.TXT - contains the latest information regarding this release 

¢ \include - contains OS Open include files 

¢ \Id - contains dynamically loadable modules that can be run from OS Open’s OpenShell 

¢ \lib - contains OS Open libraries 

« \m4- contains assembler preprocessor include files 

* \openbios - contains the source code for the ROM Monitor (See Chapter 7, “ROM Monitor”) 

¢ \samples - contains samples programs that can be compiled and run 

Considerable effort goes into providing a quality product with consistent documentation. To insure that 
our customers have the advantage of the latest software features and updated information, 


README.TXT contains clarifications and additional information and should be considered essential 
reading. 


\COMMENT.USR and \COMMENT.DOC 


Please take the time to complete these user comment forms. Your feedback and suggestions will help 
us to improve our products and technical publications. FAX and e-mail instructions are included in 
each of the files. 


3.1.2 High C/C++ Evaluation Compiler Installation - PC 

Before beginning the installation, you must have: 

¢ High C/C++ for PC installation diskettes 

* APC running Windows 95/98 or Windows NT 4.0 

The following procedure installs the High C/C++ compiler: 

Note: For Windows NT users, we recommend that you log on as administrator. 


1. Insert the installation diskette labeled “High C/C++ - PC” and “1 of n” (n may vary) into diskette 
drive A: 


2. Select Start from the Windows task bar. 

3. Select Run. 

4. Type a:setup then press Enter to run the installation program. 
5. Follow the installation program instructions. 


If the default install directory is accepted, the IBM High C/C++ Compiler is installed in the \highcppc 
directory tree. The \highcppc\bin directory contains the files required for the IBM High C/C++ 
Compiler. Those files include: 

* asppc.exe - assembler for assembler language programs 

¢ Idppc.exe - ELF linker/binder to build applications to be run on the board 

* hcppc.exe - High C/C++ compiler for C programs 

* arppc.exe - ELF library archiver 


3-2 PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


— Preliminary Copy 


The readme file under the \highcppc directory contains the latest information regarding the compiler 
and should be considered essential reading. 
3.1.3. RISCWatch Debugger Installation - PC 


Please refer to the RiSCWatch Debugger Installation Guide for debugger installation instructions. Be 
sure to follow the instructions for PC installation. 


3.2 Sun Software Installation 


3.2.1. BSP Software Installation - Sun 


The software support package is installed from diskettes on a Sun host system using the cpio and tar 
commands. 


Before beginning the installation, you must have: 
¢ BSP for Sun installation diskettes 


¢ A Sun SPARCstation 5, 10, or 20 workstation running SunOS 4.1.3 (or higher) or Solaris 2.4 (or 
higher) 


¢ Superuser privileges on the Sun system 


The procedures required for installing the BSP software support package vary depending on the 
operating system being used. Please follow the instructions corresponding to your operating system. 


Instructions for SunOS 4.1.3 (or higher) only: 

1. Log in as root or use the su command to become the superuser 
. Open at least two windows for this procedure 

. Use the ed command to change to the /usr directory 


. Insert the installation diskette labeled “BSP - Sun” and “1 of n” (n may vary) into the diskette drive 


a fF WwW PY 


. From the second window run the command: 
cpio -ivB BSP_os4.tar.Z BSP.tar.Z < /dev/rfd0 
where /dev/rfd0 is the name of your diskette device. 


6. When the system prompts you for a new volume, move to the first window and type eject to eject 
the diskette. Insert the next diskette. 


7. Move to the second window and type the name of the diskette drive (/dev/rfd0) to continue the 
process. 


8. If prompted for more diskettes, repeat the previous two steps. When finished, type eject to remove 
the final diskette. 


9. Return to the first window and verify that the following files are installed under the /usr directory: 
BSP.tar.Z 
BSP_os4.tar.Z 
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10.Run the following commands to unpack and install the files (order is important): 
zcat BSP.tar.Z | tar xvf - 
zcat BSP_os4.tar.Z | tar xvf - 
Installation for SunOS is complete. The tar.Z files may be removed to recover space. 
Instructions for Solaris 2.4 (or higher) only: 
1. Log in as root or use the su command to become the superuser. 
2. Open at least two windows for this procedure. 
3. Use the cd command to change to the /usr directory. 
4. Insert the installation diskette labeled “BSP - Sun” and “1 of n” (n may vary) into the diskette drive. 
5 


. From the first window type volcheck. This creates a file called /vol/dev/rdiskette0/unlabeled (the 
diskette device name). 


If the system opens a message box saying the diskette format is unrecognized, ignore the 
message and cancel the message box. The name of the file created may be different on your 
system. You can use the eject -q command to see the actual name. The file name returned is the 
name that should be used in the subsequent steps. 


6. From the second window run the command: 
cpio -ivB BSP.tar.Z < /vol/dev/rdiskette0/unlabeled 
where /vol/dev/rdiskette0/unlabeled is the name of your diskette device. 


7. When the system prompts you for a new volume, move to the first window. Type eject if the system 
did not automatically eject the diskette. Insert the next diskette and type volcheck. 


8. Move to the second window and type the name of the diskette drive 
(/vol/dev/rdiskette0/unlabeled) to continue the process. 


9. If prompted for more diskettes, repeat the previous two steps. When finished, type eject to remove 
the final diskette. 


10.Return to the first window and verify that the following file is installed under the /usr directory: 
BSP.tar.Z 

11.Run the following command to unpack and install the files: 
zcat BSP.tar.Z | tar xvf - 


Installation for Solaris is complete. The tar.Z file may be removed to recover space. 


The BSP software is installed in the /usr/osopen directory tree. It may be necessary to change 
ownership of these directories, their subdirectories and their contents if other users require access to 
them. 


The /usr/osopen directory tree contains the files and tools that support OS Open application and 
ROM development. The /usr/osopen subdirectories and their contents are as follows. 
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/bin 

This directory contains several host based utilities used for application and ROM program 
development. 

* elf2rom - creates a ROM image from an ELF executable file 

¢ eimgbld - creates a ROM Monitor loadable image from an ELF executable file 

¢ hbranch - places an absolute branch in the last address of a ROM image 

* rambuild - creates an assembler source file that contains the files found in a specified directory 
* bootpd - bootp server to support ROM Monitor downloads 


/examples 
This directory contains example OS Open programs. 
/m405_evb 


This directory contains the ROM Monitor and OS Open platform specific code for the reference board 
included in the kit. 

¢ README.TXT - contains the latest information regarding this release 

¢ /include - contains OS Open include files 

¢ /Id - contains dynamically loadable modules that can be run from OS Open’s OpenShell 

¢ /lib - contains OS Open libraries 

« /m4 - contains assembler preprocessor include files 

* /openbios - contains the source code for the ROM Monitor (See Chapter 7, “ROM Monitor”) 

¢ /samples - contains samples programs that can be compiled and run 

Considerable effort goes into providing a quality product with consistent documentation. To insure that 
our customers have the advantage of the latest software features and updated information, 


README.TXT contains clarifications and additional information and should be considered essential 
reading. 


/COMMENT.USR and /COMMENT.DOC 

Please take the time to complete these user comment forms. Your feedback and suggestions will help 
us to improve our products and technical publications. FAX and e-mail instructions are included in 
each of the files. 

3.2.2 High C/C++ Evaluation Compiler Installation - Sun 

The compiler is installed from diskettes on a Sun host system using the cpio and tar commands. 
Before beginning the installation, you must have: 

¢ “High C/C++ for Sun” installation diskettes 


¢ A Sun SPARCstation 5, 10, or 20 workstation running SunOS 4.1.3 (or higher) or Solaris 2.4 (or 
higher) 


* Superuser privileges on the Sun system 


The procedures required for installing the High C/C++ compiler vary depending on the operating 
system being used. Please follow the instructions corresponding to your operating system. 
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Instructions for SunOS 4.1.3 (or higher) only: 


12 


Log in as root or use the su command to become the superuser. 


2. Open at least two windows for this procedure. 
3. 
4 


. Insert the installation diskette labeled “High C/C++ - Sun” and “1 of n” (n may vary) into the diskette 


Use the cd command to change to the /usr directory. 


drive. 


. From the second window run the command: 


cpio -ivB BSP_hcppc.tar.Z < /dev/rfd0 


where /dev/rfdO is the name of your diskette device. 


. When the system prompts you for a new volume, move to the first window and type eject to eject 


the diskette. Insert the next diskette. 


. Move to the second window and type the name of the diskette drive (/dev/rfdQ) to continue the 


process. 


. If prompted for more diskettes, repeat the previous two steps. When finished, type eject to remove 


the final diskette. 


. Return to the first window and verify that the following file is installed under the /usr directory: 


BSP_hcppc.tar.Z 


10.Run the following command to unpack and install the files: 


zcat BSP_hceppc.tar.Z | tar xvf - 


Installation for SunOS is complete. The tar.Z file may be removed to recover space. 


Instructions for Solaris 2.4 (or higher) only: 


as 


. Log in as root or use the su command to become the superuser. 
. Open at least two windows for this procedure. 
. Use the cd command to change to the /usr directory. 


. Insert the installation diskette labeled “High C/C++ - Sun” and “1 of n” (n may vary) into the diskette 


drive. 


. From the first window type volcheck. This creates a file called /vol/dev/rdiskette0/unlabeled (the 


diskette device name). 


If the system pops up a message box saying the diskette format is unrecognized, ignore the 
message and cancel the message box. The name of the file created may be different on your 
system. You can use the eject -q command to see the actual name. The file name returned is the 
name that should be used in the subsequent steps. 


. From the second window run the command: 


cpio -ivB BSP_hcppe.tar.Z < /vol/dev/rdiskette0/unlabeled 


where /voldev/rdiskette0/unlabeled is the name of your diskette device. 


. When the system prompts you for a new volume, move to the first window. Type eject if the system 


did not automatically eject the diskette. Insert the next diskette and type volcheck. 
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8. Move to the second window and type the name of the diskette drive 
(/vol/dev/rdisketteO0/unlabeled) to continue the process. 


9. If prompted for more diskettes, repeat the previous two steps. When finished, type eject to remove 
the final diskette. 


10.Return to the first window and verify that the following file is installed under the /usr directory: 
BSP_hcppc.tar.Z 

11.Run the following command to unpack and install the files: 
zcat BSP_hcppc.tar.Z | tar xvf - 

Installation for Solaris is complete. The tar.Z file may be removed to recover space. 


The IBM High C/C++ Compiler is installed in the /usr/highcppc directory tree. It may be necessary to 
change ownership of these directories, their subdirectories and their contents if other users require 
access to them. The /usr/highcppc/bin directory contains the files required for the IBM High C/C++ 
Compiler. Those files include: 


* asppc - Assembler for assembler language programs 

¢ Idppe - ELF linker/binder to build applications to be run on the board 
¢ heppce - High C/C++ compiler for C programs 

* arppc - ELF library archiver 


The readme file under the /usr/highcppc directory contains the latest information regarding the 
compiler and should be considered essential reading. 


If you installed the compiler into a directory other than /usr/highcppc, edit the bin/hcppc.cnf file, and 
locate the line near the top of the file that reads HCDIR=/usr/highcppc. Change this to reflect the 
directory that the compiler was installed into. Save your changes and exit the editor. 


3.2.3. RISCWatch Debugger Installation - Sun 


Please refer to the RiSCWatch Debugger Installation Guide for debugger installation instructions. Be 
sure to follow the instructions for Sun installation. 


3.3. RS/6000 Software Installation 


3.3.1. BSP Software Installation - RS/6000 
Before beginning the installation, you must have: 


¢ BSP for RS/6000 installation diskettes 
« ARISC System/6000, running AIX Version 4.1 or higher 
¢ Superuser privileges on the AIX system 


The following procedure installs the BSP software support package. 
1. Log in as root or use the AIX su command to become the superuser. 
2. Use the cd command to change to the /usr directory. 


3. Insert the installation diskette labeled “BSP - RS6K” and “1 of n” (7 may vary) into the diskette drive 
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4. Issue the following command: 
tar -xvf /dev/rfd0 
where /dev/rfd0 is the name of your diskette device 


5. When the system prompts you for the next media, eject the diskette, insert the next diskette, and 
press Enter. 


6. If prompted for more media, repeat the previous step for the remaining BSP diskettes. When 
finished, remove the final diskette from the diskette drive. 


7. Verify that the following file is installed under the /usr directory: 
BSP.tar.Z 
8. Run the following command to unpack and install the files: 


zcat BSP.tar.Z | tar xvf - 
Installation for AIX is complete. The tar.Z file may be removed to recover space. 


The BSP software is installed in the /usr/osopen directory tree. It may be necessary to change 
ownership of these directories, their subdirectories and their contents if other users require access to 
them. 


The /usr/osopen directory tree contains the files and tools that support OS Open application and 
ROM development. The /usr/osopen subdirectories and their contents are as follows. 

/bin 

This directory contains several host based utilities used for application and ROM program 
development. 

* elf2rom - creates a ROM image from an ELF executable file 

* eimgbld - creates a ROM Monitor loadable image from an ELF executable file 

¢ hbranch - places an absolute branch in the last address of a ROM image 

* rambuild - creates an assembler source file that contains the files found in a specified directory 
* trc41 - post-processes OS Open trace snapshots for AIX 4.1 


/examples 
This directory contains example OS Open programs. 
/m405_evb 


This directory contains the ROM Monitor and OS Open platform specific code for the reference board 
included in the kit. 

¢ README.TXT - contains the latest information regarding this release 

¢ /include - contains OS Open include files 

¢ /Id - contains dynamically loadable modules that can be run from OS Open’s OpenShell 

¢ /lib - contains OS Open libraries 

« /m4 - contains assembler preprocessor include files 

* /openbios - contains the source code for the ROM Monitor (See Chapter 7, “ROM Monitor”) 

« /samples - contains samples programs that can be compiled and run 
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Considerable effort goes into providing a quality product with consistent documentation. To insure that 
our customers have the advantage of the latest software features and updated information, 
README.TXT may contain clarifications and/or additional information and should be considered 
essential reading. 


/COMMENT.USR and COMMENT.DOC 


Please take the time to complete these user comment forms. Your feedback and suggestions will help 
us to improve our products and technical publications. FAX and e-mail instructions are included in 
each of the files. 


3.3.2 High C/C++ Evaluation Compiler Installation - RS/6000 
Before beginning the installation, you must have: 

¢ High C/C++ for RS/6000 installation diskettes 

¢ ARISC System/6000, running AIX Version 4.1 or higher 

¢ Superuser privileges on the AIX system 

The following procedure installs the High C/C++ compiler. 

1. Log in as root or use the AIX su command to become the superuser. 

2. Use the cd command to change to the /usr directory. 


3. Insert the installation diskette labeled “High C/C++ - RS6K” and “1 of n” (n may vary) into the 
diskette drive 


4. Issue the following command: 
tar -xvf /dev/rfd0 
where /dev/rfd0 is the name of your diskette device 


5. When the system prompts you for the next media, eject the diskette, insert the next diskette, and 
press Enter. 


6. If prompted for more media, repeat the previous step for the remaining High C/C++ diskettes. 
When finished, remove the final diskette from the diskette drive. 


7. Verify that the following file is installed under the /usr directory: 
BSP_hcppc.tar.Z 

8. Run the following command to unpack and install the files: 
zcat BSP_hcppe.tar.zZ | tar xvf - 

Installation for AIX is complete. The tar.Z file may be removed to recover space. 


The IBM High C/C++ Compiler is installed in the /usr/highcppce directory tree. It may be necessary to 
change ownership of these directories, their subdirectories and their contents if other users require 
access to them. The /usr/highcppc/bin directory contains the files required for the IBM High C/C++ 
Compiler. Those files include: 
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* asppc - assembler for assembler language programs 

¢ Idppce - ELF linker/binder to build applications to be run on the board 
* heppce - High C/C++ compiler for C programs 

* arppc - ELF library archiver 


The readme file under the /usr/highcppce directory contains the latest information regarding the 
compiler and should be considered essential reading. 


If you installed the compiler into a directory other than /usr/highcppc, edit the bin/hcppc.cnf file, and 
locate the line near the top of the file that reads HCDIR=/usr/highcppc. Change this to reflect the 
directory that the compiler was installed into. Save your changes and exit the editor. 


3.3.3. RISCWatch Debugger Installation - RS/6000 


Please refer to the RiSCWatch Debugger Installation Guide for debugger installation instructions. Be 
sure to follow the instructions for RS/6000 installation. 
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Chapter 4. Host Configuration 


Several host configuration steps are required to facilitate communications between the host computer 
and the board. These steps are outlined in this chapter. Please refer to the section corresponding to 
your host system. 


4.1. PC Host Configuration 


The following sections discuss setup of host configuration for PC hosts. 


4.1.1. Serial Port Setup - PC 


Most PCs include two serial ports to support communications via asynchronous data transfer. These 
ports are sometimes referred to as communication or COM ports. These ports are usually accessed 
from the back of the system unit. You should consult your PC literature to determine how many serial 
ports are available on your unit and where they are located. In this section, S1 and S2 refer to the 

respective serial ports on the host PC, and SP1 and SP2 to the respective serial ports on the board. 


When properly configured, one serial port can be used to connect a terminal emulator running on the 
host to the ROM Monitor running on the board, and the other to provide a Serial Line Internet Protocol 
(or SLIP) network interface between the host and the board to download and debug applications. The 
SLIP host-to-board connection is optional if the recommended Ethernet connection is going to be 
used for host-to-board communications. This section addresses the proper configuration of the S1 
and S2 serial ports to support these connections. Users should also refer to the Windows on-line help 
for “Changing Serial Port Settings’. 


The connection of the terminal emulator running on the host to the ROM Monitor running on the 
board, is made through the S1 serial port on the PC and the SP1 (J11 lower) serial port on the board. 
The S1 port must be configured for a baud rate of 9600, 8 data bits, 1 stop bit, and no parity. The 
proper setting of these parameters is discussed later in the section on terminal emulation. 


A connection between the S2 serial port on the host and the SP2 (J11 upper) serial port on the board, 
provides a SLIP network interface to download and debug application programs from the host. This 
connection can be used in place of the recommended Ethernet connection. 


Note: Windows users who want to establish a SLIP host-to-board connection over a second serial 
port, require additional software since the TCP/IP package that comes with Windows does not 
support SLIP communications. Trumpet Winsock is one package that supports the SLIP 
protocol. Trumpet is not recommended for Windows users already connected to a network 
since installing Trumpet may cause problems with previously defined networks. If the 
recommended Ethernet host-to-board connection is going to be used (instead of a SLIP host- 
to-board connection), Windows users do not need to install Trumpet since the TCP/IP package 
that comes with Windows can be used to establish the Ethernet connection. 


To establish a SLIP network over the S2 serial port for host-to-board communications, define a SLIP 
interface via the TCP/IP package being used. Since TCP/IP packages for PCs vary, users should 
consult their TCP/IP literature or their system administrator on how to establish the SLIP interface 
between the host and the board. The following IP addresses are suggested for the SLIP interface: 
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« PC host (source): 8.7.1.4 

¢ Board (destination): 8.7.1.5 

Make a note of the IP addresses selected since they will be needed later. 

Trumpet Winsock users can use the following steps as a guide to establishing the SLIP interface: 


1. Open the Trumpet Winsock by double clicking on the Trumpet Winsock icon in the Trumpet 
Winsock Files program group. 


2. If setup was bypassed during installation, your connection should fail. A Trumpet Winsock window 
comes up indicating your connection status. Select Setup from the File menu to open the Setup 
dialog. 


3. Set the IP address field to the IP address of the PC host: 8.7.1.4 is suggested to maintain 
consistency with this document. 


. Select SLIP under Drivers and then go to Dialler settings. 
. Select the appropriate COMM port (COM2 for example) to be used for SLIP communications. 
. Set the Baud rate to 38400. 


. Disable Hardware handshaking and make sure No automatic login is selected. Use the default 
settings for the remaining options and/or check the help for more details. 


N © OF f 


8. Select OK from Dialler Settings and then OK from Setup. 


9. Edit the hosts file found in the installed Trumpet directory to include both the PC host IP address 
and the board IP address. For example: 


8.1.1.4 — local_slip 
8.1.1.5 board_slip 


After entering all the information, you may need to restart Trumpet Winsock for the network setup to 
take effect. 


Prior to exiting Windows, we recommend terminating Trumpet Winsock (close the application). If you 
do not follow this recommendation, subsequent Trumpet starts may fail. If this occurs, you will need to 
reboot your system. 


4.1.2 Ethernet Setup - PC 


In addition to (or in place of) the SLIP connection, an Ethernet connection can be used for host-to- 
board communications. The Ethernet connection is made through an Ethernet adapter on the host 
and the 10BaseT/100BaseTX Ethernet port (J22) on the board. Ethernet is much faster than SLIP 
and is recommended when downloading large applications on to the board or when using the 
RISCWatch debugger. 


An Ethernet connection may require additional hardware. The reference board supports a standard 
Ethernet, twisted pair (10BaseT/100BaseTX) connection. This connection requires that the host PC 
be equipped with an appropriate Ethernet adapter. The host adapter is not included in the kit. Please 
consult your PC and adapter documentation for requirements and installation instructions. 


Ata minimum, a 10BaseT/100BaseTX connection requires a crossover Ethernet twisted pair cable 
(included in the kit) for point-to-point communications. The Ethernet crossover cable is for 10Mb/s 
direct connection to a single host and cannot be used with a hub or a building’s Ethernet network. If 
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you want more than two nodes, or 100Mb/s connectivity, you will need a hub and straight-through 
twisted pair cables. 


Other hardware required will depend on the type of Ethernet adapter you have on your PC and 
whether the board is being connected to an existing Ethernet network. Please consult your system 
administrator and the documentation included with the adapter hardware for additional instructions. 


Establishment of an Ethernet interface requires a host IP address. If the host PC is connected to an 
existing Ethernet network, the host IP address should already be defined and there is no need to set 
it again. Consult your network administrator on how to obtain the host’s Ethernet IP address and how 
to add the board to the existing network. 


To set the host IP address for the Ethernet connection: 
1. Select the My Computer icon from the desktop. 

2. Select Control Panel. 

3. Select Network. 
4 


. Add the appropriate Adapter network component for the Ethernet adapter being used (if not 
already added). 


5. Add a Protocol network component of Microsoft - TCP/IP’ (if not already added). Specify the IP 
address (7.1.1.4 is recommended to maintain consistency with this document) and netmask 
(255.255.240.0) to be used. 


For the update to take effect, TCP/IP may need to be restarted. This may require a reboot of the 
system and/or a restart of TCP/IP. Make a note of the host IP address assigned to the Ethernet 
adapter, as this value will need to be made known to the ROM Monitor on the board. 


4.1.3. ROM Monitor-Debugger Communication Setup - PC 


Before the RISCWatch Debugger can be used, some additional steps need to be taken to establish 
ROM Monitor-Debugger communications. These steps involve an update of the TCP/IP services file 
to establish a named communications port and port number for TCP/IP socket communications, and 
a restart of the TCP/IP package for the update to take effect. 


Windows 95/98 places the services file under C:\WINDOWS\SERVICES. Windows NT places the 
services file under C:'WINDOWS\SYSTEM32\DRIVERS\SERVICES. Users should consult their 
TCP/IP documentation or system administrator if they can not locate the file. The following lines must 
be added to the file: 


osopen-dbg 20044/tcp # for RISCWatch OS Open debug 
osopen-dbg 20044/udp # for RISCWatch rom_mon debug 


For the update to take effect, TCP/IP needs to be restarted. This might require a reboot of the system 
and a restart of the TCP/IP package. 


4.2 Sun Host Configuration 


Sun configuration requires that you be the superuser of the host workstation. This is accomplished by 
logging in as root or by using the su command to become the superuser. 
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4.2.1 Serial Port Setup - SUN 


The Sun workstation includes two serial ports to support communications via asynchronous data 
transfer. These ports are labeled Serial A and Serial B on the back of the Sun’s system unit. Some 
SPARCstation models multiplex these two ports into one physical port labeled A/B (use A if it’s 
available since use of the B port requires a special de-multiplexing cable from Sun). This section 
refers to these ports as S1 and S2, respectively. When properly configured, one of the serial ports can 
be used to connect a terminal emulator running on the host to the ROM Monitor running on the board. 
This connection is made through the S1 serial port on the Sun and the SP1 (J11 lower) serial port on 
the board. 


The S1 port on the host must be configured for a baud rate of 9600, 8 data bits, 1 stop bit, and no 
parity. The proper setting of these parameters is discussed later in the section on terminal emulation. 


4.2.2 Ethernet Setup - SUN 


Since all Sun SPARCstations come equipped with an Ethernet (or AUI) port, an Ethernet connection 
is used for host-to-board communications. The reference board supports a Standard Ethernet, 
twisted pair (10BaseT/100BaseTX) connection. An Ethernet connection may require additional 
hardware. 


Ata minimum, a 10BaseT/100BaseTX connection requires a crossover Ethernet twisted pair cable 
(included in the kit) for point-to-point communications. The Ethernet crossover cable is for 10Mb/s 
direct connection to a single host and cannot be used with a hub or a building’s Ethernet network. If 
you want more than two nodes, or 100Mb/s connectivity, you will need a hub and straight-through 
twisted pair cables. 


Establishment of an Ethernet interface requires a host IP address. If the host SPARCstation is 
connected to an existing Ethernet network, the host IP address should already be defined. Consult 
your network administrator on how to obtain the host’s Ethernet IP address and how to add the board 
to the existing network. 


If the host SPARCstation is not connected to an existing Ethernet network, then a network between 
the board and the host must be established. The ifconfig command can be used to establish such a 
network. Users should consult their network administrator and Sun documentation for additional 
information. A host IP address of 7.1.7.4 is suggested to maintain consistency with this document. 


Make a note of the host's IP address since it will need to be made known to the ROM Monitor on the 
board. 


4.2.3. ROM Monitor-Debugger Communication Setup - SUN 


Before the RISCWatch Debugger can be used, the TCP/IP services file must be updated to allow 
ROM Monitor-Debugger communications. 


To modify the /etc/services file, you need to log in as root or the superuser (su). The following lines 
must be added to the file: 


osopen-dbg 20044/tcp # for RISCWatch OS Open debug 


osopen-dbg 20044/udp # for RISCWatch rom_mon debug 
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4.3. RS/6000 Host Configuration 


RS/6000 configuration requires that you be the superuser of the host workstation. This is 
accomplished by logging in as root or by using the AIX su command to become the superuser. 


4.3.1. Serial Port Setup - RS/6000 


The RS/6000 includes two serial ports to support communications via asynchronous data transfer. 
These ports are labeled S1 and S2 on the back of the RS/6000’s system unit. When properly 
configured, one serial port can be used to connect a terminal emulator running on the host to the 
ROM Monitor running on the board, and the other to provide a Serial Line Internet Protocol (or SLIP) 
network interface between the host and the board to download and debug applications. This section 
addresses the proper configuration of the S1 and S2 serial ports to support these connections. 
Details on setting up the terminal emulator are discussed in a later chapter. In this section, S1 and S2 
refer to the respective serial ports on the host RS/6000, and SP1 and SP2 to the respective serial 
ports on the board. 


The connection of the terminal emulator running on the host to the ROM Monitor running on the 
board, is made through the S1 serial port on the RS/6000 and the SP1 (J11 lower) serial port on the 
board. A connection between the S2 serial port on the host and the SP2 (J11 upper) serial port on the 
board, provides a SLIP network interface to download and debug application programs on the board. 
If the recommended Ethernet connection is going to be used, the S2-to-SP2 SLIP connection is 
optional and does not need to be established. 


Proper setup involves the configuration of tty devices for both the S1 and S2 serial ports on the host. 
tty0 is used for the terminal emulator-to-ROM Monitor connection and tty1 for the host-to-board SLIP 
connection. It is also necessary to establish a SLIP network interface between S2 on the host and 
SP2 on the board. The following steps should be taken to insure proper S1, S2 configuration: 


1. Log in as root or the superuser (su). 
2. Determine if the tty0, tty1 devices already exist. 
a. Enter smit 
b. Select Devices 
c. Select TTY 
d. Select List All Defined TTYs 
Perform step 3 for each tty not listed. 
Perform step 4 for each tty listed to insure that it is properly configured. 
3. To add a tty device: 
a. Return to the TTY screen. 
b. Select Add a TTY. 
c. Select tty rs232 Asynchronous Terminal. 
d. Select sa0 - Serial Port 1 (for ROM Monitor connection) when adding tty0. 
OR sat - Serial Port 2 (for board SLIP connection) when adding tty1. 
e. Select s1 for the port number when adding tty0. 
OR s2 for the port number when adding tty1. 
f. Ensure that the BAUD rate is 9600 when adding tty0. 
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OR that the BAUD rate is 38400 when adding tty1. 
g. Ensure that the PARITY is none. 
h. Ensure that the BITS per character is 8. 
i. Ensure that the Number of STOP BITS is 1. 
j. Ensure that Enable LOGIN is disabled. 
The default settings for all the other fields are satisfactory. 
k. Select Do or press Enter. 


Upon successful completion, a properly configured tty device is created and thus, step 4 can 
be skipped for the particular tty (ttyO or tty1) added. Remember to repeat this step, step 3, if 
both ttyO and tty1 needed to be added. 


4. To properly configure a previously defined tty device: 


a. Return to the TTY screen. 


b. Select Change/Show Characteristics of a TTY. 

c. Select tty# (where # = 0 or 1). 

d. Ensure that the following fields are set to the indicated values: 
TTY tty# (#=0 for tty0, 1 for ttyl) 
TTY type tty 
TTY interface S232 
Description Asynchronous Terminal 
Status Available 
Location 00-00-S*-00 (*=1 for tty0, 2 for ttyl) 
Parent Adapter sa# (#=0 for tty0, 1 for ttyl) 
Port Number s* (*=1 for tty0, 2 for ttyl) 
Terminal Type dumb 
Enable LOGIN disable 


e. Ensure that the BAUD rate is 9600 for tty0. 
OR that the BAUD rate is 38400 for tty1. 
f. Ensure that the PARITY is none. 
g. Ensure that the BITS per character is 8. 
h. Ensure that the Number of STOP BITS is 1. 
The other fields can remain at their default values. 
i. Select Do or press Enter. 
Upon successful completion, the tty device is properly configured. 

5. This last step establishes the SLIP network over the tty1 device between the host and the board. 
It's optional for those using the recommended Ethernet connection for host-to-board 
communications. This step is not required for ttyO since it is being used simply for terminal 
emulation. Unlike a LAN interface, a SLIP connection is point-to-point. We first need to specify an 


IP address for the host and then an IP address for the other end of the SLIP connection, which in 
this case, is the reference board. To do this: 


a. Enter smit. 
b. Select Communication Applications and Services. 
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c. Select TCP/IP. 

d. Select Further Configuration. 

e. Select Network Interfaces. 

f. Select Network Interface Selection. 

g. Select Add a Network Interface. 

h. Select Add a Serial Line INTERNET Network Interface. 

i. Select tty1. 

j. Set the INTERNET ADDRESS field the host’s IP address. An acceptable value would be 8. 7.7.4. 


k. Set the DESTINATION Address field to the reference board’s IP address. An acceptable value 
would be 8.7.7.5. 


Use of these IP addresses are recommended to maintain consistency with the rest of the 
documentation. Make a note of the IP addresses selected, as they will need to be made 
known to the ROM Monitor on the board. 

Set the Network MASK to 255.255.240.0. 

.Ensure that ACTIVATE is yes. 

. Ensure that the TTY PORT is tty1. 

. Leave the BAUD RATE field blank. 

. Leave the DIAL STRING field blank. 

. Select Do or press Enter. 
Upon successful completion, the SLIP Network Interface is established over tty1 and the 
serial port setup is complete. 
If this step fails, insure that a SLIP Network has not already been defined over tty1. To make 
this check, return to the Network Interface Selection screen in smit and select List All 
Network Interfaces. If sI1 is listed then a network interface has already been defined for tty1 
and its characteristics may need to be changed. Return to the Network Interface Selection 
screen and select Change/Show Characteristics of a Network Interface. Select sl1 and 
insure that the fields are set as stated previously in this step. 

There is no need to change the IP addresses in the INTERNET ADRRESS and 
DESTINATION address fields if they have already been defined, but use of the above 


mentioned IP addresses is strongly recommended to maintain consistency with this 
documentation. 


Q2T0 05 3 


4.3.2 Ethernet Setup - RS/6000 


In addition to (or in place of) the SLIP connection, an Ethernet connection can be used for host-to- 
board communications. The Ethernet connection is made through an Ethernet adapter on the host 
and the 10BaseT/100BaseTX Ethernet port (J22) on the board. Ethernet is much faster than SLIP 
and is recommended when downloading large applications on to the board or when using the 
RISCWatch debugger. 


An Ethernet connection may require additional hardware. The reference board supports a Standard 
Ethernet, twisted pair (10BaseT/100BaseTX) connection. This connection requires that the host PC 
be equipped with an appropriate Ethernet adapter. The host adapter is not included in the kit. Please 
consult your PC and adapter documentation for requirements and installation instructions. 
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Ata minimum, a 10BaseT/100BaseTX connection requires a crossover Ethernet twisted pair cable 
(included in the kit) for point-to-point communications. The Ethernet crossover cable is for 10Mb/s 
direct connection to a single host and cannot be used with a hub or a building’s Ethernet network. If 
you want more than two nodes, or 100Mb/s connectivity, you will need a hub and straight-through 
twisted pair cables. 


Other hardware required will depend on the type of Ethernet adapter you have on your RS/6000 and 
whether the board is being connected to an existing Ethernet network. AIX Communications 
Concepts and Procedures (GC23-2203, two volumes) has additional information about the 
management and configuration of a TCP/IP network, including specifics as to how to configure an 
Ethernet network interface. Some of the basic steps are outlined below. You should consult your 
network administrator before attempting Ethernet setup. 


1. The host must be equipped to participate in a 10BaseT/100BaseTX Ethernet network. This may 
require the installation of an Ethernet adapter card for your specific RS/6000 model and, as 
discussed previously, additional connectivity hardware. Consult the documentation included with 
the hardware for installation instructions. Most RS/6000 models come with Ethernet adapters 
already installed. They are labeled ET in the back of the RS/6000 system unit. 


2. Assuming the host system is equipped with the appropriate Ethernet adapter, the Ethernet 
interface must be configured properly. To do this: 
a. Log in as root or the superuser (su). 
b. Enter smit. 

c. Select Communication Applications and Services. 

d. Select TCP/IP. 

e. Select Further Configuration. 

f. Select Network Interfaces. 

g. Select Network Interface Selection. 

h. Select Add a Network Interface. 

i. Select Add a Standard Ethernet Network Interface. 


Choose Standard Ethernet as opposed to IEEE 802.3 Ethernet. If you receive an error 
message stating that there is “No available adapter”, go to step 3 and skip the remaining 
items in this step. 


j. Select end. 


k. Set the INTERNET ADDRESS field to the host IP address. This value must be different from that 
used for the SLIP interface. It can be set to any convenient value if the Ethernet network is 
private for board development purposes. An acceptable value would be 7.7.1.4. 


Make a note of the IP address selected for the host system, as it will need to be made known 
to the ROM Monitor on the board. Note that an IP address for the board is not required as it 
was for the point-to-point SLIP network interface. An IP address for the board will, however, be 
required later on for the board setup. 


|. Set the Network MASK field to 255.255. 240.0. 
m.Ensure that ACTIVATE is yes. 

n. Ensure that the Use Address Resolution Protocol is yes. 
0. Leave the BROADCAST ADDRESS blank 

p. Select Do or press Enter. 


4-8 PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


— Preliminary Copy 


Upon successful completion, a properly configured Ethernet interface has been added. The 
Ethernet setup is complete and step 3 need not be performed. 


3. Perform this step only if you received the “No available adapter” error message when trying to Add 
a Standard Ethernet Network Interface in step 2. This message indicates that either the Ethernet 
adapter is missing (or possibly misplugged) or the Ethernet Network Interface already exists. To 
determine if the interface already exists: 


a. Return to the Network Interface Selection screen in smit. 


b. Select Change/Show Characteristics of a Network Interface. 


If enO is not listed, insure that the RS/6000 host does have an Ethernet adapter and, if 
possible, that it is plugged correctly. If the adapter was misplugged, repeat step 2 to add the 
Ethernet Network Interface. 

if enO is listed, then the Ethernet Network Interface already exists. Select enO and note the IP 
address listed for the INTERNET ADDRESS field. This value is the host’s Ethernet IP address 
and will be needed later. If no IP address is listed, choose one. The IP address 7.7.1.4 can be 
used to maintain consistency with the menus and examples in this document. The Ethernet 
setup is complete. 


4.3.3. ROM Monitor-Debugger Communication Setup - RS/6000 


Before the RISCWatch Debugger can be used, some additional steps need to be taken to establish 
ROM Monitor-Debugger communications. These steps involve an update of the TCP/IP services file 
and a refresh of the TCP/IP inetd daemon. 


To modify the /etc/services file, you need to log in as root or the superuser (su). The following lines 
must be added to the file: 


osopen-dbg 20044/tcp # for RISCWatch OS Open debug 
osopen-dbg 20044/udp # for RISCWatch rom_mon debug 


The AIX refresh -s inetd command must then be run to inform the inetd daemon of the changes 
made to the /etc/services file. 
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Chapter 5. Hardware 


The PPC405GP design kit includes the reference board which contains the following features: 
* PowerPC PPC405GP processor, which includes: 


— PowerPC 405 core 

— 10BaseT/100 Base TX (RJ45) Ethernet 
— Two 16550-type serial ports 

— IIC (I2C) port 

— General Purpose Timers 

— Interrupt Controller 

— PC-100 SDRAM Controller with support for ECC 
— DMA controller 

— ROM/Peripheral controller 

— Internal PCI Controller 

— General-purpose I/Os 


¢« Memory 


— 16MB SDRAM, single DIMM socket, support up to 128MB 
512KB socketed flash memory 

— 512KB SRAM 

Support for ECC 

¢ Real-time clock with 8KB NVRAM and battery-backup 


* Four 32-bit PCI connectors 


* Keyboard/mouse controller 
¢ IR controller 
¢« Aseparate PCI VGA display adapter is also included with the board 


For detailed descriptions of the reference board specifications, features, and its memory mapping, 
please refer to the PowerPC 405 Reference Board Manual. 
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Chapter 6. Board Connectors 


For detailed descriptions of the connectors and jumpers on the reference board, please refer to the 
PowerPC 405 Reference Board Manual. 


6.1 Connecting the Reference Board to the Host 

To establish a working environment, the reference board must be connected to a host system. ROM 
Monitor access requires a connection between the serial port on the board (J11 lower) and the S1 
(COM1) serial port on the host. Users must also establish a connection for debug and downloading 


applications from the host to the board. This connection is made over the SLIP or Ethernet network 
established during host configuration. 


Host F 
Evaluation Board 


| [|] Ethernet Port (J22) 


SLIP 
—— | Serial Port 1 (J11 lower) 


Serial Port 2 (J11 upper) 


$2 (Com2) 


Terminal Emulator 
Running on 
Host $1 (Com1) 


Figure 6-1. Serial Port Connection 


Included in the PowerPC 405GP Reference Design Kit is an interface cable supporting either 9-pin or 
25-pin serial port connections. Assuming a terminal emulator running on the host is going to be used 
for ROM Monitor access, connect the 9-pin serial port connector on one end of a cable to the J11 
lower serial port connector on the board, and the other end of the same cable to the S1 (COM1) serial 
port on the host. The host end might require a serial port adapter (not supplied) for connectivity. Sun 
SPARCstation users might require the 25-pin male-to-male adapter (included in the Sun version of 
the kit) at the host end. If a SLIP connection is going to be used for host-to-board communications, 
connect a serial interface cable (not provided) from the J11 upper serial port connector on the board 
to the S2 (COM2) serial port on the host. 


The Ethernet connection can be made in two ways. If the connection is to be used exclusively 
between the host and the board, and only 10Mb/s speed is required, the provided crossover cable 
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can be used to directly connect the two nodes. Otherwise, a 10BaseT or 100BaseTx hub (not 
provided) must be used to connect the nodes together. 


Note: The Ethernet 10BaseT crossover cable supplied will not work if plugged into a hub. 


Figure 6-2 shows the connections and signal assignments required in a crossover cable: 


RJ-45 Connector 10BaseT Cable RJ-45 

Twisted Signal Signal 
Pair Name Pin Pin Name 

1 TD + 1 1 TD + 

1 TD - 2 2 TD - 

2 RD + 3 3 RD + 

2 RD - 6 6 RD —- 
3,4 (Not 4,5,7,8 4,5,7,8 (Net 
used) used) 


Figure 6-2. Wiring in a Crossover Cable 


Figure 6-3 shows a point-to-point Ethernet connection using the provided crossover cable: 


Ethernet 
Adapter Evaluation Board 


10BaseT 
Greseeve|_——_ Ethernet Port (J22) 


Cable 


Serial Port 1 (J11 lower) 


im Serial Port 2 (J11 upper) 


Terminal Emulator 
Running on 
Host 


S1 (Com1) 


Figure 6-3. Point-to-Point Ethernet Connection 


Figure 6-4 shows an Ethernet connection using a hub: 
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10 BaseT / 
100 BaseTx 
Hub 


Host 


Ethernet 


Adapter 10BaseT / 100BaseTx 


Straight-through Cable 


Evaluation Board 


Ethernet Port (J22) 


Terminal Emulator Serial Port 1 (J11 lower) 
Running on 


Host S1 (Com1) 


Serial Port 2 (J11 upper) 


Figure 6-4. Ethernet Connection with Hub 


If the connection is to be made to an existing Ethernet network, users should consult their Network 
Administrator to insure proper connectivity. Users wanting to use both a SLIP and Ethernet 
connection can do so, as long as both networks have been configured properly and the proper 
connections have been made. 


6.2 Using a Terminal Emulator 


The ROM Monitor transmits/receives data through serial port 1 (J11 lower) on the board. Access to 
the ROM Monitor can be achieved by connecting a VT100 (or compatible) terminal directly to serial 
port 1 (J11 lower) on the board or by using a terminal emulator running on the host. When using a 
terminal emulator, access is obtained via a connection between the serial port 1 connector on the 
board and an available serial (or COM) port on the host system. 


6.2.1. PC Terminal Emulation 


Once all the host-to-board connections have been properly made and power has been supplied to the 
board, the Windows HyperTerminal program can be used as a terminal emulator to support 
communications with the ROM Monitor. The steps for setting up the terminal emulator connected to 
COM1 are as follows: 


1. Select Start from the Windows 95/98/NT task bar. 
2. Select Programs. 
3. Select Accessories. 


4. Select HyperTerminal. 
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5. If you see a window that says "You need to install a modem before you can make a connection. 
Would you like to do this now?” click on "No". You do not need a modem to connect to the board. 


6. Select the Hypertrm icon. 
7. Enter a name, for example "PPCEVB" and select an icon. 


8. Select the following: 
Connect using Direct to Com 1 (default) 
Bits per second — 9600 
Data bits — 8 (default) 
Parity — None (default) 
Stop Bits — 1 (default) 
Flow Control — Xon/Xoff 


9. Select OK. 


After resetting the board, the ROM Monitor menu should appear in the HyperTerminal window. If it 
does not, check your HyperTerminal settings and ensure proper connectivity between the host and 
the board. 


6.2.2 SUN Terminal Emulation 


The Terminal Interface Program (TIP) can be used as a terminal emulator to support communications 
with the ROM Monitor. When properly configured, TIP connects the host Sun SPARCstation to a 
remote system, which in our case is the board. To set up TIP, do the following: 


1. Log in as root or the superuser (su). 
2. Go to the /ete directory (cd /etc). 
3. See if the file, remote, exists (Is remote). If the file does not exist, create it. 


4. Using an editor, add the following line to the remote file (cut and pasters can find this line in the 
README.TXT file): 


tty0:dv=/dev/ttya:br#9600:el=*U*C*%S*Q*%D: ie=%$ :oe=*D:pa=none: 


5. Exit from root. 


TIP configuration is complete. Once all the host-to-board connections have been properly made and 
power has been supplied to the board, TIP can be activated by typing tip tty0O at the command 
prompt. After resetting the board, the ROM Monitor main menu should appear in the window where 
tip was activated. It might be necessary to press Enter once or twice to get the menu to appear for the 
first time. If the ROM Monitor menu does not appear, consult your System Administrator — the ttya 
device might need to be modified. Additional information on TIP can be found in the on-line man 
pages by typing man tip. 
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Some useful escape sequences to know when using TIP include: 


~? Help for TIP 

~CTRL-D Instructs the TIP command to terminate the connection and exit 
~# Sends a break to the remote system 

~s script Starts recording of transmissions made by the remote system 


Note: Recordings are made in the default tip.record file in the user's 
current directory 


~s !script Stops recording of transmissions made by the remote system 


Note 1: It might be necessary to press Enter or CTRL-D before entering these escape sequences. 


Note 2: If a terminal emulator other than TIP is used, it must be configured for 9600 bps, eight bits 
per character, one stop bit, and no parity. 


6.2.3. RS/6000 Terminal Emulation 


The AIX Terminal Interface Program (TIP) can be used as a terminal emulator to support 
communications with the ROM Monitor. When properly configured, TIP connects the host RISC/6000 
to a remote system, which in our case is the board. To set up TIP, do the following: 


1. Log in as root or the superuser (su). 

2. Go to the /ete directory (cd /etc). 

3. See if the file, remote, exists (Is remote). If the file does not exist, create it. 
4 


. Using an editor, add the following line to the remote file (cut and pasters can find this line in the 
README.TXT file): 


tty0:dv=/dev/tty0:br#9600:e1=*U*C*S*Q%D: 1e=%3$ : 0e=*D: pa=none: 


5. Exit from root. 


TIP configuration is complete. Once all the host-to-board connections have been properly made and 
power has been supplied to the board, TIP can be activated by typing tip ttyO at the AIX command 
prompt. After resetting the board, the ROM Monitor main menu should appear in the window where 
tip was activated. It might be necessary to press Enter once or twice to get the menu to appear for the 
first time. Additional information on TIP can be found in AlX Communications and Procedures (GC23- 
2203, two volumes). 


Revised 8/22/00 v. 0.8 Board Connectors 6-5 


—Preliminary Copy 


Some useful escape sequences to know when using TIP include: 


ene Help for TIP 

~CTRL-D Instructs the TIP command to terminate the connection and exit 
~# Sends a break to the remote system 

~s script Starts recording of transmissions made by the remote system 


Note: Recordings are made in the default tip.record file in the user's 
current directory 


~s !script Stops recording of transmissions made by the remote system 


Note 1: It might be necessary to press Enter before entering these escape sequences. 


Note 2: If a terminal emulator other than TIP is used, it must be configured for 9600 bps, eight bits 
per character, one stop bit, and no parity. 


6.3 Board Reset 


When the connectors have been installed and power is applied to the board, you must first press the 
board’s On/off switch to power up the board. Pressing the Reset switch causes the processor and the 
communications controllers to reset. After the ROM Monitor (resident in flash) initializes the processor 
and board peripherals, the monitor menu is displayed if a properly configured terminal (or terminal 
emulator) is attached to serial port 1 (J11 lower) of the board. Details of ROM Monitor operation are 
provided in Chapter 7, “ROM Monitor.” 
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Chapter 7. ROM Monitor 


This chapter describes the ROM Monitor program, also known as OpenBlOS. This ROM resident 


program provides chip (and board level) initialization and a user interface menu that supports board 
diagnostics, program downloads, and debug. 


7.1. ROM Monitor Source Code 


The ROM Monitor source code is provided for ROM development purposes. This code is separate 


from the OS Open and sample application code described in Chapter 8. The ROM Monitor code is 
loosely organized by function in the following subdirectories and files within the 
\osopen\m405_evb\openbios directory (/usr/osopen/m405_evb/openbios for SUN and RS/6000 


users). 


makefile.mak 
Makefile 
devTab.c 
include/ 

m4/ 

ppcLib/ 
enetLib/ 
ioLib/ 
miscLib/ 
s1Lib/ 
s1IdLib/ 
dbLib/ 
entry.s 

lib/ 

netLib/ 
slipLib/ 
align_h.s 
mapfile1 
bios ***.map 
flash/ 


Revised 8/22/00 


Top level makefile to create ROM monitor image (PC) 


Top level makefile to create ROM monitor image (RS/6000 & SUN) 


Handles boot device definitions 

C include files 

assembler preprocessor include files 

C callable functions to access PowerPC special instructions 
Ethernet chip specific code 

I/O helper functions 

Miscellaneous routines used for ROM monitor 

Serial Port interface routines 

Code to support S1 serial port downloads 

Ptrace debug interface routines 

Processor and C environment initialization 

Repository for intermediate libraries 

IP and UDP processing functions 

SLIP implementation 

Alignment handling code 

Mapfile to specify ROM Monitor linkage directives 

Load map of the ROM Monitor version *** shipped with the board 
Code to support re-programming the flash memory 
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7.2 Communications Features 


The ROM Monitor runs as part of the boot code in the flash memory on the board. The monitor 
communicates with an asynchronous terminal (or terminal emulator) attached to serial port 1 (SP1) 
on the board, through which the user accesses the monitor menu. The ROM Monitor can download 
applications and communicate with the host debugger through serial port 2 (SP2) or the Ethernet 
adapter, depending on which devices are enabled. Communications between SP2 and the host use 
the Serial Link Internet Protocol (SLIP), while Ethernet communications use the Internet Protocol (IP) 
over standard Ethernet. The ROM Monitor also supports the downloading of programs via serial 
port 1, but not debug. To use this feature, a VT100 terminal emulator that supports binary file 
transfers (such as kermit) must be used on the host system. 


7.3 Configuration of bootp and tftp to Support ROM Monitor Loads 


Both the debugger and the ROM Monitor can be used to load applications onto the board. Details on 
how to use the debugger can be found in the RISC Watch Debugger User's Guide. To use the facilities 
of the ROM Monitor for downloading applications to the board, the host workstation must be 
configured to support the bootp protocol and tftp daemons. The configuration consists of two parts. 
The bootptab file on the host must be customized to match system requirements, and the bootp and 
tftp daemons (or servers) must be made available. 


7.3.1. PC bootp and tftp Configuration 


Not all TCP/IP packages include the bootpd and tftpd servers required for ROM Monitor downloads. 
For this reason both the bootpd and tftpd servers have been included in the BSP software package 
under the \osopen\bin directory. These servers can be installed and used in conjunction with 
Windows Socket compliant TCP/IP packages that come with Windows 95/98 and Windows NT. 


Configuration consists of two parts. The bootptab and services files on the host must be customized 
to match system requirements, and the bootpd and tftpd servers must be made available. If you 
choose to use the bootpd and tftpd servers provided with this package, you will need to modify your 
autoexec.bat file to specify the location of the bootptab and services files. This is accomplished by 
adding a line that sets up an ETC environment variable to specify the directory where the bootptab 
and services files are located (e.g., set etc=c: \windows for Windows 95/98, 

set etc=c:\winnt\system32\drivers\etc. for Windows NT 4.0). Consult your TCP/IP 
documentation or contact your system administrator if the services file cannot be found. 


A sample bootptab file, \osopen\m405_evb\samples\bootptab.sam, is included with the BSP 
software. This file can be copied to the ETC directory set in the autoexec.bat file and modified 
appropriately. Note that the bootptab file in the ETC directory must be named bootptab with no file 
extension. Entries describing the board to the host PC must be added to the bootptab file. 


When creating or modifying the bootptab file, the following rules apply: 
¢ Blank lines and lines beginning with “#’ are ignored. 
¢ Each entry must be entered on a single line. 


¢ Each entry must start with a host name followed by the legends (see the sample booiptab file for 
legend descriptions). 


« Use “:” to separate each legend and leave no spaces between legends. 
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¢ User must supply the host IP address via the “ip” legend. 


« Ifthe “hd” (home directory) & “bf” (bootfile) legends are not provided for a particular entry, the first 
defined “hd” and “bf” legends in the bootptab file will be taken as default. 


File entries similar to those below would be suitable. 


slipc:hd=\osopen\m405_evb\samples:bf=boot.img:bs:ip=8.1.1.5:sm=255.255.255.255 
enetc:ht=ethernet :hd=\osopen\m405_evb\samples:bf=boot.img:bs:ip=7.1.1.5: 
sm=255.255.255.255:ha=xxxxxxXXXXXXX 


Each of the entries, slipc and enetc, should be entered on a single line. The value of the Ethernet 
hardware address field in the enetc entry, ha=xxxxxxxxxxxx, should match the twelve character 
hardware address listed for the Ethernet Boot Source on the ROM Monitor menu. 


Both connections use the file \osopen\m405_evb\samples\boot.img as the source for the 
application image to be downloaded onto the board. Be sure that the ht=ethernet keyword is used for 
the Ethernet connection entry and that the IP addresses are those of the board. Note that the IP 
address in the slipc entry must match that of the IP address assigned to the board during serial port 
setup. Since a board IP address was not required for Ethernet setup, the IP address used in the enetc 
entry defines the IP address of the board for the Ethernet connection. If the suggested bootptab 
entries are used, 7.1.1.5 would be the board’s Ethernet IP address. Take note of the board’s IP 
addresses, since they must be made known to the ROM Monitor. 


The services file (no file extension) must also exist in the ETC directory set in the autoexec.bat file. 
It must be updated with the port and protocol information for the bootpd and tftpd servers. To use the 
servers provided with this package, the following entries must be included in the services file: 


bootps 67/UDP 
bootpe 68/UDP 
tftp 69/UDP 


For the update to take effect, TCP/IP needs to be re-started. This may require a reboot of the system 
and/or a restart of the TCP/IP package. After that, the bootpd and tftpd servers are ready for use. 


You may choose to run bootpd.exe and tftpd.exe automatically every time that WIndows is started or 
you can run these programs only when needed. To make these program run automatically every time 
Windows is started perform the following steps: 


1. Select Start from the Windows task bar. 
. Select Settings. 

. Select Taskbar. 

. Select Start Menu Programs. 

. Select Add... 


. In the command line field enter the following: 


oOo a fF W PD 


BOOTPD -c C -h 7.1.1.4 
where C is the driver letter containing the boot image and 7.1.7.4 is the host IP address 
7. Select Next. 


8. In the Select Program Folder window, select the Programs/Startup folder. 
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9. Select Next. 

10.Select Finished. 

11.To start tftp follow the above steps, but enter the following in the command line field: 
TFTPD 


The bootp and tftp daemons will be started automatically upon the next restart of Windows. 


7.3.2 SUN bootp and tftp Configuration 


The Solaris and SunOS operating systems both provide a tftpd server but do not provide a bootpd 
server. For this reason a bootpd server has been included in the BSP software package under the 
/usr/osopen/bin directory. 


A sample bootptab file, /usr/osopen/m405_evb/samples/bootptab.sam, is included with the BSP 
software. This file should be copied to the /ete directory and renamed bootptab if a bootptab file 
does not already exist. You will need to log in as root or the superuser (Su) to update or add files in 
the /etc directory. Entries describing the evaluation board to the host workstation must be added to 
the bootptab file. 


When creating or modifying the bootptab file, the following rules apply: 
¢ Blank lines and lines beginning with “#’ are ignored. 
¢ Each entry must be entered on a single line. 


« Each entry must start with a host name followed by the legends (see the sample booiptab file for 
legend descriptions). 


¢ Use “:” to separate each legend and leave no spaces between legends. 
¢ User must supply the host ip address via the “ip” legend. 


« Ifthe “hd” (home directory) & “bf” (bootfile) legends are not provided for a particular entry, the first 
defined “hd” and “bf” legends in the bootptab file will be taken as default. 


File entries similar to those below would be suitable. 


slipc:hd=\osopen\m405_evb\samples:bf=boot.img:bs:ip=8.1.1.5:sm=255.255.255.255 
enetc:ht=ethernet :hd=\osopen\m405_evb\samples:bf=boot.img:bs:ip=7.1.1.5: 
sm=255.255.255.255:ha=xxxxxXXXXXXX 


Each of the entries, slipc and enetc, should be entered on a single line. The value of the Ethernet 
hardware address field in the enetc entry, ha=xxxxxxxxxxxx, should match the twelve character 
hardware address listed for the Ethernet Boot Source on the ROM Monitor menu. 


Both connections use the file /usr/osopen/m405_evb/samples/boot.img as the source for the 
application image to be downloaded onto the board. Be sure that the ht=ethernet keyword is used for 
the Ethernet connection entry and that the IP addresses are those of the board. Note that the IP 
address in the slipe entry must match that of the IP address assigned to the board during serial port 
setup. Since a board IP address was not required for Ethernet setup, the IP address used in the 
enetc entry defines the IP address of the board for the Ethernet connection. If the suggested 
bootptab entries are used, 7.7.7.5 would be the board’s Ethernet IP address. Take note of the 
board’s IP addresses, since they must be made known to the ROM Monitor. 
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To start the bootpd and tftpd servers: 
1. Log in as root or the superuser (su). 


2. Ensure that the following entries are included in the /etc/services file: 


bootps 67/udp 
bootpe 68/udp 
tftp 69/udp 


3. Ensure that the tftp entry in the /etc/inetd.conf file is uncommented and modify as follows: 
tftp dgram udp wait root /usr/etc/in.tftpd in.tftpd -s / 

4. Add an entry for the bootpd server in /etc/inetd.conf as follows: 
bootps dgram udp wait root /usr/osopen/bin/bootpd bootpd —i 

5. Reconfigure inetd for the updates made to the inetd.conf file. First find the process ID for inetd: 
ps -ef | grep inetd (Solaris) 
ps -auex | grep inetd (SunOS) 

6. Send a hang-up signal to reconfigure inetd: 
kill -HUP <process id> 


bootp and tftp configuration is complete. 


7.3.3 RS/6000 bootp and tftp Configuration 


To modify the /etc/bootptab file, you need to log in as root or the superuser (su). Entries describing 
the evaluation board to the host workstation must be added to this file. Complete details describing 
the bootptab file format are available in the AlX Command Reference under “bootpd”. File entries 
suitable for our purposes are shown below. 


slipc:hd=\osopen\m405_evb\samples:bf=boot.img:bs:ip=8.1.1.5:sm=255.255.255.255 
enetc:ht=ethernet :hd=\osopen\m405_evb\samples:bf=boot.img:bs:ip=7.1.1.5: 
sm=255.255.255.255:ha=xxxxxxXXXXXXX 


Each of the entries, slipc and enetc, should be entered on a single line. The value of the Ethernet 
hardware address field in the enetc entry, ha=xxxxxxxxxxxx, should match the twelve character 
hardware address listed for the Ethernet Boot Source on the ROM Monitor menu. 


Both connections use the file /usr/osopen/m405_evb/samples/boot.img as the source for the 
application image to be downloaded onto the board. Be sure that the ht=ethernet keyword is used for 
the Ethernet connection entry and that the IP addresses are those of the board. Note that the IP 
address in the slipe entry must match that of the IP address assigned to the board during serial port 
setup. Since a board IP address was not required for Ethernet setup, the IP address used in the 
enetc entry defines the IP address of the board for the Ethernet connection. If the suggested 
bootptab entries are used, 7.7.7.5 would be the board’s Ethernet IP address. Take note of the 
board’s IP addresses, since they must be made known to the ROM Monitor. 


To start the bootp and tftp daemons on systems running AIX 4, do the following: 
1. Log in as root or the superuser (su). 


2. Enter smit. 
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3. Select Processes and Subsystems. 

4. Select Subservers. 

5. Select Start a Subserver. 

6. Select bootps. 

7. Select OK. 

Upon successful completion, bootp configuration is complete. Select Done and continue for tftp. 
1. Select Start a Subserver. 

2. Select tftp. 

3. Select OK. 

4. Select Done. 


Upon successful completion, tftp configuration is complete. Select Exit to leave smit. 


7.4 Accessing the ROM Monitor 


The ROM Monitor expects a real or emulated VT100 type ASCII display attached to serial port 1 with 
line protocol parameters of 9600 bps, eight bits per character, no parity, and one stop bit. Once the 
terminal connected to SP1 is configured properly, you can access the ROM Monitor menu options, 
use the ping test, and load an application onto the board. 


The ROM Monitor also provides the interface to the RISCWatch debugger. This facility, along with the 
image download process, is accessed via an IP network connection to the host workstation. Network 
configuration of the host was discussed earlier in the chapter on host configuration. The actual 
connection is either via SLIP (Serial Link Interface Protocol) running on serial port 2 at speeds up to 
56Kbps, or via standard Ethernet using the 10BaseT/100BaseTX Ethernet port on the board. 


7.5 ROM Monitor Operation 


The ROM Monitor requires a block of DRAM for its operation and makes some assumptions about 
applications loaded on the board. Some of these assumptions may be disregarded if you do not need 
the ROM Monitor to interface with a debugger or otherwise support communication between the host 
workstation and the board. 


Applications wishing to coexist with the ROM Monitor must observe the following constraints. 


« Provide exception vectors for application events starting at address 0x0000 0000. For example, an 
application’s external interrupt handler should be located at Ox0000 0500. This is handled for you 
when using OS Open. 


¢ Use storage addresses between 0x0002 5000 and the end of DRAM only, except for application 
vectors. 


¢ Do not alter the EVPR register. 
¢ Do not start applications lower than address 0x0002 5000. 
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Figure 7-1 shows the address map of the reference board under control of the ROM Monitor. 


OxFFFF FFFF 
ROM Monitor Code (Flash) 
OxFFFE 0000 


0x0100 0000 


(end of DRAM) 
Application Area 
0x0002 5000 
ROM Monitor Area (DRAM) 
0x0000 2000 


Application Vectors 0x0000 0000 


Figure 7-1. ROM Monitor Address Map 


7.6 Monitor Selections and Submenus 


At this point it is assumed that the host has been properly configured, all board connections have 
been made, power has been supplied, and the terminal emulator running on the host has been 
configured and started successfully. The main menu, shown below, is displayed after the board has 
been reset and the ROM Monitor completes initialization. Note that some of the values you see, in 
particular the ROM Monitor version, the IP addresses, and the Ethernet controller's hardware 
address, may differ with those shown below. 


Each menu option is described separately in the following sections. “Local” in the context of the ROM 
Monitor IP addressing means the IP address assigned to the board, while “remote” means the IP 
address assigned to the host workstation. Using option 8 to save changes made to the configuration 
will allow the new values to persist beyond subsequent power-on or resets. The ROM Monitor 
supports this by storing its configuration data in NVRAM. 
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7.6.1. Initial ROM Monitor Menu 
The following menu is displayed after the boa 


405GP 1.3 ROM Monitor (7/6/99) 


SAP Ste SaaS SSeS Ress aa= System Info 


rd has been reset. 


Processor = A4O5GP, PVR: 40110000 
Processor speed = 200 MHz 

PLB speed = 100 MHz 

Ext Bus speed = 50MHz 

PCI Bus speed = 33 MHz (Sync) 

Amount of SDRAM = 16 MBytes 


External PCI arbiter enabled 


--- Device Configuration --- 
Power-On Test Devices: 
000 Enabled System Memory [ 
001 Enabled Ethernet [ENET] 
004 Enabled Serial Port 2 [ 
Boot Sources: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 
004 Enabled Serial Port 2 
local=8.1.1.5 
005 Enbaled Serial Port 1 
Baud=9600 


[ 


[ 


Debugger: Disabled 


RAM] 


S2] 


remote=7.1.1.4 
S2] 
remote=8.1.1.4 
$1] 


on 


1 - Enable/disable tests 
2 - Enable/disable boot devices 
3 - Change IP addresses 
4 - Ping test 
5 - Toggle ROM monitor debugger 
6 - Toggle automatic menu 
7 - Display configuration 
8 - Save changes to configurati 
9 - Set baud rate for sl boot 
A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
0 - Exit menu and continue 
-—> 
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7.6.2 Selecting Power-On Tests 


Option 1 in the main menu selects power-on tests. These tests are run when the menu exits and 
before the ROM loader begins the bootp processing. 


—- Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 

- Toggle automatic menu 

Display configuration 

- Save changes to configuration 

- Set baud rate for sl boot 

- Enable/disable I cache (Enabled ) 
—- Enable/disable D cache (Enabled ) 
—- Exit menu and continue 


| 
Vv 
POW POANHDAUBAWNHE 
| 


When option 1 is selected, the following submenu is displayed. 


—-—- ENABLE AND DISABLE POWER-ON TESTS --- 
Power-On Test Devices: 


000 Enabled System Memory [RAM] 
001 Enabled Ethernet [ENET ] 
004 Enabled Serial Port 2 [S82] 


Select device to change -> 


Selecting a test toggles its testing status. For example, since the System Memory test is enabled in 
the above menu, selecting 0 at the prompt disables it. 


Select device to change ->0 [Selects system memory] 
After the selection has been made, the new setting is displayed, followed by the main menu. 


Select device to change ->0 
[RAM] test is disabled [Message describing change] 


--- Device Configuration --- 
Power-On Test Devices: 
000 Disabled System Memory [RAM] 
001 Enabled Ethernet [ENET ] 
004 Enabled Serial Port 2 [S82] 
Boot Sources: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Enabled Serial Port 2 [S82] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=fffffffffffFf 
005 Enbaled Serial Port 1 [S1] 
Baud=9600 
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- Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 

- Toggle automatic menu 

Display configuration 

- Save changes to configuration 

- Set baud rate for sl boot 

— Enable/disable I cache (Enabled) 
— Enable/disable D cache (Enabled) 
—- Exit menu and continue 


OUPOANDHADUABWNEH 
| 


-> 
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Remember to use Option 8 to save any configuration changes that you may have made. If the 
changes are not saved, they will be lost upon an exit from the menu or upon a board reset. 


7.6.3. Selecting Boot Devices 


Option 2 in the main menu enables and disables boot devices. 


1 - Enable/disable tests 

2 - Enable/disable boot devices 

3 - Change IP addresses 

4 - Ping test 

5 - Toggle ROM monitor debugger 

6 - Toggle automatic menu 

7 - Display configuration 

8 - Save changes to configuration 
9 - Set baud rate for sl boot 

A - Enable/disable I cache (Enabled) 
B - Enable/disable Dcache (Enabled) 
QO - Exit menu and continue 
—>2 


When option 2 is selected, the following submenu is displayed. 


-—-- ENABLE AND DISABLE BOOT DEVICES --- 
Boot Sources: 
001 Enabled Ethernet [ENET } 


local=7.1.1.5 remote=7.1.1.4 


004 Enabled Serial Port [S2] 


2 
local=8.1.1.5 remote=8.1.1.4 
1 


005 Enabled Serial Port 
Baud = 9600 


[S1] 


Select device to change -> 
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Selecting a device toggles its boot status. Selecting 4, for example, would disable Serial Port 2 as a 
boot device. 


Select device to change ->4 [Selects serial port] 


After the selection has been made, the new setting is displayed, followed by the main menu. 


Select device to change ->4 
[S2] boot is disabled [Message describing change] 


--- Device Configuration --- 
Power-On Test Devices: 
000 Disabled System Memory [RAM] 
001 Enabled Ethernet [ENET ] 
004 Enabled Serial Port 2 [S82] 
Boot Sources: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=fffffffffffFf 
005 Enbaled Serial Port 1 [S1] 
Baud=9600 


—- Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 

- Toggle automatic menu 

Display configuration 

- Save changes to configuration 

- Set baud rate for sl boot 

— Enable/disable I cache (Enabled) 
— Enable/disable D cache (Enabled) 
—- Exit menu and continue 


OUPOANDHDUABRWNEKH 
| 


When the user selects option 0 and exits from the monitor menu, the monitor attempts a boot of the 
application image on the host using the enabled boot sources in the order they are listed. In the above 
example, a boot is attempted over Ethernet since it is the first boot source enabled. If more than one 
boot source is enabled, an attempt to boot over the first enabled device is made. If that attempt fails, a 
boot over the next enabled device is attempted. 
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7.6.4 Changing IP Addresses 


Option 3 in the main menu allows users to change the IP addresses for the board and the host 
workstation. These addresses are used for bootp processing, debugger communications, and in the 
host connectivity “ping” test. 


Note: The local IP address is that of the board and the remote IP address is that of the host 
workstation. The IP addresses must match those set during host configuration. 


1 - Enable/disable tests 

2 - Enable/disable boot devices 

3 - Change IP addresses 

4 - Ping test 

5 - Toggle ROM monitor debugger 

6 - Toggle automatic menu 

7 - Display configuration 

8 - Save changes to configuration 

9 - Set baud rate for sl boot 

A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
QO - Exit menu and continue 
->3 


When option 3 is selected, the following submenu is displayed: 


-—-- CHANGE IP ADDRESS --- 
Device List: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=fffffffffffFf 


GI 


Select device to change -> 


Select the appropriate device. 


Select device to change ->1 [Selects Ethernet] 


When a valid device is selected, the following submenu is displayed. 


1 - Change local address 
2 - Change remote address 
0 - Return to main menu 


=> 


Make the appropriate selection. To change the board’s IP address, you would select option 1, Change 
local address. 


—>1 [Selects the local address] 
Current IP address = (7.1.1.5) [Displays the current value] 
Enter new IP address ->Enter IP address in dot notation (e.g., 8.1.1.2) 


Now enter the new IP address in dotted decimal notation. 


7.1.1.5 
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After the selection has been entered, the new configuration is displayed, followed by the main menu. 


--- Device Configuration --- 
Power-On Test Devices: 


000 Disabled System Memory [RAM] 


001 Enabled Ethernet 


004 Enabled Serial Port 2 


Boot Sources: 


001 Enabled Ethernet [ENET] 
local=7.1.1.5 
004 Disabled Serial Port 2 
local=8.1.1.5 
005 Enbaled Serial Port 1 


Baud=9600 


- Enable/disable tests 


- Change IP addresses 
- Ping test 


- Toggle automatic menu 
Display configuration 


- Enable/disable I cache 
—- Enable/disable D cache 
—- Exit menu and continue 


OWUPTWUOANAOBRWNHEH 
| 


=> 


remote=7.1.1.4 


remote=8.1.1.4 


- Enable/disable boot devices 


- Toggle ROM monitor debugger 


- Save changes to configuration 
- Set baud rate for sl boot 


hwaddr=1000abcdef55 


hwaddr=ffffffLrfffrtt 


This option should be repeated to set all of the IP addresses to their appropriate values. If the 
suggested IP addresses are being used, the local and remote addresses for both the Ethernet and 
the Serial Port should match those in the above menu. Remember to save any configuration changes 


via option 8. 


7.6.5 Using the Ping Test 


Option 4 in the main menu selects the ping test. The ping test can be used for a basic assurance test 
of IP connectivity to the host workstation. It should be performed after setting the IP addresses to 
insure host-to-board communications. If the ping test fails, users can not load applications on to the 
board. The local and remote addresses for the specified device are used for the source and 


destination of the ICMP ping packets. 
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1 - Enable/disable tests 

2 - Enable/disable boot devices 

3 - Change IP addresses 

4 - Ping test 

5 - Toggle ROM monitor debugger 

6 - Toggle automatic menu 

7 - Display configuration 

8 - Save changes to configuration 

9 - Set baud rate for sl boot 

A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
QO - Exit menu and continue 
—>4 


When option 4 is selected, the current configuration is displayed, followed by another command 
prompt. 


--- PING TEST --- 
Device List: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=ffffffffffff 


Select device to ping -> 


Select the appropriate device to ping (in this case only Ethernet is enabled). 


Select device to ping ->1 [selects the Ethernet port] 


If the board is able to successfully ping the host, a message similar to the following should appear: 


Using [ENET] to ping. press any key to stop. 

PING 7.1.1.4 56 data bytes 

78 bytes from 7.1.1.4: icmp_seq=0 tt1l=255 time=2 ms 
78 bytes from 7.1.1.4: icmp_seq=2 tt1=255 time=1 ms 
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Pressing any key terminates the ping test. The main menu is redisplayed following the PING status 
report. 


--- 7.1.1.4 ping statistics --- 

2 packets transmitted, 2 packets received, 0% packet loss 
Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 

- Toggle automatic menu 

Display configuration 

- Save changes to configuration 

- Set baud rate for sl boot 

— Enable/disable I cache (Enabled) 
— Enable/disable D cache (Enabled) 
—- Exit menu and continue 


OWUPTWUOANAHAUBWNHEH 
| 


-> 
If the ping test fails, 


¢ Verify that the local and remote IP addresses are set correctly. The local IP address should be that 
of the board and the remote IP address should be that of the host. These IP addresses were 
assigned during host configuration (see earlier chapter). 


¢ Verify that the cables are connected properly. 
¢ Verify TCP/IP is running on the host. 


Note: The ROM Monitor will not respond to an inbound ping test from the host unless the ROM 
Monitor is in Debug mode (via options 5 and 0) or the ROM Monitor ping test is active on the 
board at the same time (via option 4). 


7.6.6 Entering the Debugger 


Option 5 toggles the feature of the ROM Monitor that allows communication with the host based 
source level debugger. Debugging may be enabled/disabled, and saved as part of the configuration 
using option 8. The debugger is not actually called by the monitor until after the user exits the main 
menu by selecting option 0 (exit and continue). 


--- Device Configuration --- 
Power-On Test Devices: 


000 Disabled System Memory [RAM] 
001 Enabled Ethernet [ENET ] 
004 Enabled Serial Port 2 [S82] 


Boot Sources: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
5 
Hk 


local=8.1.1. remote=8.1.1.4 hwaddr=fffffffftfftft 
005 Enbaled Serial Port [S1] 
Baud=9600 
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1 - Enable/disable tests 
2 - Enable/disable boot devices 
3 - Change IP addresses 
4 - Ping test 
5 - Toggle ROM monitor debugger 
6 - Toggle automatic menu 
7 - Display configuration 
8 - Save changes to configuration 
9 - Set baud rate for sl boot 
A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
QO —- Exit menu and continue 
>5 


ROM monitor debugger will be active on exit 


7-16 


- Enable/disable tests 


- Enable/disable boot devices 


- Change IP addresses 
- Ping test 


- Toggle ROM monitor debugger 


- Toggle automatic menu 


- Save changes to configuration 
- Set baud rate for sl boot 
—- Enable/disable I cache (Enabled) 
— Enable/disable D cache (Enabled) 


1 
2 
3 
4 
i) 
6 
7 - Display configuration 
8 
9 
A 
B 
0 


- Exit menu and continue 
>7 


--- Device Configuration --- 
Power-On Test Devices: 


000 Disabled System Memory [RAM] 
[ENET ] 
004 Enabled Serial Port 2 [S82] 


001 Enabled Ethernet 


Boot Sources: 


001 Enabled Ethernet [ENET] 


local=7.1.1. 
004 Disabled Serial Port 

local=8.1.1. 
005 Enbaled Serial Port 

Baud=9600 


5 


2 
2 
1 


remote=7.1.1.4 
[S2] 

remote=8.1.1.4 
[S1] 
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Debugger : Enabled (on exit) 

1 - Enable/disable tests 

2 - Enable/disable boot devices 

3 - Change IP addresses 

4 - Ping test 

5 - Toggle ROM monitor debugger 

6 - Toggle automatic menu 

7 - Display configuration 

8 - Save changes to configuration 

9 - Set baud rate for sl boot 

A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
QO -— Exit menu and continue 

->0 


PowerPC ROM Monitor Debugger 


Waiting for debug command... 
Press any key to exit 


Use option 8 to save the state of the ROM Monitor debugger. This option in combination with option 6, 
“Toggle automatic menu”, can be used to configure the board to automatically wait for the debugger to 
attach after power-on. 


The ROM Monitor debugger only communicates over Ethernet or Serial Port 2 (SLIP) so one of these 
boot devices must be enabled when using the ROM Monitor debugger. After enabling the ROM 
Monitor debugger (via option 5) and selecting option 0, the RISCWatch debugger can be started on 
the host and used to load an application onto the board. This is assuming the RISC Watch 
environment file has been updated for ROM Monitor communications. Once loaded successfully, the 
application can be run from the debugger. 


The RISCWatch Debugger User's Guide contains more information on how to use the debugger to 
load and execute files with the ROM Monitor as a non-JTAG target. At this point, it is recommended 
that users become familiar with the debugging environment by following the “Quick Start” sample 
debug session in the debugger’s User’s Guide. This session takes a user through the basics, 
including how to use the debugger to load and run applications on the board. 


7.6.7 Disabling the Automatic Display 


Option 6 in the main menu disables the automatic monitor display when the board boots up. After 
option 6 has been selected and the configuration has been saved (via Option 8), the menu display is 
disabled but continues to function until the user exits from the main menu. Following the next power- 
on or reset, the menu is no longer automatically displayed. This allows the user’s image to be 
downloaded automatically with no menu input required. This feature also allows a user to download 
an application with no cable connected to the serial port 1 on the board (that is, without a terminal 
emulator). 


After the automatic menu display has been disabled, the main menu can be accessed (assuming a 
terminal emulator is attached successfully to SP1 on the board) by pressing any key during the first 
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five seconds that the board is booting. Otherwise, application download processing starts without 
displaying the main menu. 


7.6.8 Displaying the Current Configuration 


Option 7 displays the current configuration. 


OUPrODAINHDHDUBRWNE 


| 
Vv 
~I 


Enable/disable tests 
Enable/disable boot devices 
Change IP addresses 

Ping test 

Toggle ROM monitor debugger 
Toggle automatic menu 

Display configuration 

Save changes to configuration 
Set baud rate for sl boot 
Enable/disable I cache (Enabled) 
Enable/disable D cache (Enabled) 
Exit menu and continue 


--- Device Configuration --- 
Power-On Test Devices: 


000 Disabled System Memory [RAM] 
001 Enabled Ethernet [ENET ] 
004 Enabled Serial Port 2 [S82] 


Boot Sources: 


001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 
004 Disabled Serial Port 2 [S2] 
5 
1 


local=8.1.1. remote=8.1.1.4 
005 Enbaled Serial Port [S1] 
Baud=9600 


Debugger : Enabled (on exit) 


OUPOANINDHDUABWNEH 


—- Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 

- Toggle automatic menu 

- Display configuration 

- Save changes to configuration 

- Set baud rate for sl boot 

— Enable/disable I cache (Enabled) 
— Enable/disable D cache (Enabled) 
—- Exit menu and continue 


hwaddr=1000abcdef55 


hwaddr=ffffffLrfffrtt 


When a menu operation is selected to alter configuration settings, the current configuration is 
automatically redisplayed. 
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7.6.9 Saving the Current Configuration 


Option 8 saves the current configuration for subsequent power-on resets. 


— Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 

-— Toggle automatic menu 

Display configuration 

- Save changes to configuration 

- Set baud rate for sl boot 

—- Enable/disable I cache (Enabled) 
— Enable/disable D cache (Enabled) 
—- Exit menu and continue 


OUPruODAINDHDUBWNHE 
| 


->8 
Configuration has been saved 

1 - Enable/disable tests 
Enable/disable boot devices 
- Change IP addresses 
- Ping test 
- Toggle ROM monitor debugger 
- Toggle automatic menu 
Display configuration 
- Save changes to configuration 
- Set baud rate for sl boot 
- Enable/disable I cache (Enabled) 
- Enable/disable D cache (Enabled) 
—- Exit menu and continue 


OwUruoOwDANATA UO BWDND 
| 


| 
Vv 


The configuration is saved in the NVRAM on the evaluation board and is retained until a new 
configuration is subsequently saved. 


7.6.10 Setting the Baud Rate for S1 Boots 


Option 9 provides a mechanism for setting the baud rate to be used by serial port 1 when it is used as 
a device to download programs. Downloading over serial port 1 requires the use of a VT100 terminal 
emulator that supports kermit binary file transfer over serial port 1. RS/6000 and Sun users should 
note that the TIP terminal emulator does not support kermit binary file transfers. Windows 95/98/NT 
users can use HyperTerminal to perform kermit file transfers at up to 115200 baud. The kermit 
terminal emulator, available as shareware from the http://www.columbia.edu/kermit Internet site, 
can be used on any of the supported hosts to download programs over serial port 1 at speeds up to 
115200 baud. Note that the ROM Monitor debugger can not operate over serial port 1. 
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--- Device Configuration --- 
Power-On Test Devices: 
000 Disabled System Memory [RAM] 
001 Enabled Ethernet [ENET ] 
004 Enabled Serial Port 2 [S82] 
Boot Sources: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=fffffffffffFf 
005 Enbaled Serial Port 1 [S1] 
Baud=9600 


Debugger : Enabled (on exit) 


1 - Enable/disable tests 
2 - Enable/disable boot devices 
3 - Change IP addresses 
4 - Ping test 
5 - Toggle ROM monitor debugger 
6 - Toggle automatic menu 
7 - Display configuration 
8 - Save changes to configuration 
9 - Set baud rate for sl boot 
A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
QO - Exit menu and continue 
->9 


Select a baud rate for Sl boot 


1 - 9600 

2- 19200 

3. = 28800 

4 - 38400 

5s 57600 

6 - 115200 
=>4 


--- Device Configuration --- 
Power-On Test Devices: 
000 Disabled System Memory [RAM] 
001 Enabled Ethernet [ENET ] 
004 Enabled Serial Port 2 [S82] 
Boot Sources: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=fffffffffffFf 
005 Enbaled Serial Port 1 [S1] 
Baud=38400 
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Debugger : Disabled (on exit) 

—- Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 

- Toggle automatic menu 

Display configuration 

- Save changes to configuration 

- Set baud rate for sl boot 

—- Enable/disable I cache (Enabled) 
— Enable/disable D cache (Enabled) 
—- Exit menu and continue 


OWUPOANINDHDUABAWNEH 
| 


Use Option 8 to save the selected speed after reset and power-on. 


7.6.11 S1 Boot 


To perform an S1 boot you must have a terminal emulator which supports kermit file transfer. The file 
must be a valid boot image and must be sent in binary mode. If you have selected to use a baud rate 
other than 9600, you must set the terminal emulator to run at that speed before loading the file and 

set the speed back to 9600 after the download is complete. The following example shows loading the 


usr_samp.img file. 


--- Device Configuration --- 
Power-On Test Devices: 
000 Disabled System Memory [RAM] 
001 Disabled Ethernet [ENET] 
004 Disabled Serial Port 2 [S2] 


Boot Sources: 
001 Disabled Ethernet [ENET] 


004 Disabled Serial Port 2 [S2] 


005 Enbaled Serial Port 1 [S1] 
Baud=38400 


Debugger: Disabled 

—- Enable/disable tests 

- Enable/disable boot devices 

- Change IP addresses 

- Ping test 

- Toggle ROM monitor debugger 
Toggle automatic menu 

- Display configuration 

- Save changes to configuration 
- Set baud rate for sl boot 

— Enable/disable I cache (Enabled) 


POANA OB WNHEH 
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local=7.1.1.5 remote=7.1.1.4 


local=8.1.1.5 remote=8.1.1.4 


hwaddr=1000abcdef55 


hwaddr=ffffffLrLfffrtt 
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B - Enable/disable D cache (Enabled) 
0 - Exit menu and continue 

->0 

Booting from [S1] Serial Port 1... 


PLEASE NOTE: You must now... 


Exit from terminal emulation mode 

Modify the baud rate of your host session 
Transmit a file to the target in binary mode 
Reset the host baud rate to 9600 

Reenter terminal emulation mode 

Hit enter to execute the downloaded program 


hoaadanaso wo 


At this point kermit users must get to the terminal emulator command mode and change the line 
speed to match what was selected by option 9 and tell the terminal emulator to send the file in binary 
format. 


A\c (Cnirl-\c) 

(Back at waterdeep) 
C-Kermit>set speed 38400 
/dev/tty0, 38400 bps 
C-Kermit>set file type bin 


You can now load the file. 


C-Kermit>send usr_samp.img 

SF 

Type escape character (*\) followed by: 

X to cancel file, CR to resend current packet 

Z to cancel group, A for status report 

E to send Error packet, Ctrl-C to quit immediately: 


Sending: usr_samp.img => USR_SAMP.IMG 
Size: 164864, Type: binary 


ZB 
When loading is completed, you must change the line speed back to 9600 bps before continuing. 


C-Kermit>set speed 9600 
/dev/tty0, 9600 bps 
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After setting the line speed back to 9600 bps, re-connect to your terminal emulator and press Enter to 
complete the download. 


C-Kermit>con 

Connecting to /dev/tty0, speed 9600. 

The escape character is Ctrl-\ (ASCII 28, FS) 

Type the escape character followed by C to get back, 
or followed by ? to see other options 


Loaded successfully ... 
Entry point at Ox25f20 ... 


Hello 405GP user! 


Your ROM Monitor version is : 1.3 


Your 405GP Evaluation Board has 16777216 bytes of DRAM installed. 


Your Ethernet controller’s network address is : 1000abcdef55 


usr_samp done! 


Assuming the S1 boot baud rate has been set to 38400 and option 0 has been selected to exit the 
ROM Monitor menu and initiate a load, Windows HyperTerminal users can initiate the kermit binary 
file transfer by performing the following steps: 


1. Select Call and then Disconnect. 


2. Select File, Properties, Configure and set the baud to match the baud rate set via ROM Monitor 
option 9. In this case, it is 38400. 


3. Select OK and OK again. 

4. Select Call and then Connect. 

5. Select Transfer, Send File and type the file name of the file to load. Set the Protocol to Kermit. 
6. Select Send. 

Upon successful completion of the transfer, the baud rate must be changed back to 9600. 

7. Select Call and then Disconnect. 

8. Select File, Properties, Configure and set the baud to 9600. 

9. Select OK and OK again. 

10.Select Call and then Connect. 


11.Press Enter to complete the download sequence. 


7.6.12 Exiting the Main Menu 


Option 0 exits from the main menu, leaving the monitor active. If the debugger is active prior to 
selecting option 0, the ROM Monitor waits for the user to start the debugger on the host. In all other 
cases, option 0 initiates an attempt by the ROM Monitor to load an application from the host to the 
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board over the enabled boot device(s). When downloading over the Ethernet or SLIP (S2), the host 

bootp and tftp configuration must be completed for the ROM Monitor to load an application program 

successfully. Upon exit of the menu, the ROM Monitor will send a bootp request to the host to obtain 
the name of the file to download. Once the bootpd server returns the appropriate file name as set in 
the bootptab file, the ROM Monitor sends a tftp request to the tftpd server on the host to transfer file. 
Once the file is loaded successfully, it is executed. 


When serial port 1 is used, the ROM Monitor requires the user to follow additional instructions to 
complete the download. The example shown here describes the sequence required when programs 
are downloaded over serial port 1. 


--- Device Configuration --- 
Power-On Test Devices: 
000 Disabled System Memory [RAM] 
001 Disabled Ethernet [ENET ] 
004 Disabled Serial Port 2 [S82] 


Boot Sources: 
001 Disabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=ffffffffffff 
005 Enbaled Serial Port 1 [S1] 
Baud=38400 


Debugger : Enabled (on exit) 


1 - Enable/disable tests 
2 - Enable/disable boot devices 
3 - Change IP addresses 
4 - Ping test 
5 - Toggle ROM monitor debugger 
6 - Toggle automatic menu 
7 - Display configuration 
8 - Save changes to configuration 
9 - Set baud rate for sl boot 
A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
0 - Exit menu and continue 
->0 


Booting from [S1] Serial Port 1... 


PLEASE NOTE: You must now... 


Exit from terminal emulation mode 

Modify the baud rate of your host session 
Transmit a file to the target in binary mode 
Reset the host baud rate to 9600 

Re-enter terminal emulation mode 

Hit enter to execute the downloaded program 


hoaadanao ww 


The ROM Monitor will now wait for you to follow the above steps. The idea is that you must 
temporarily modify the terminal emulation session baud rate to match the baud rate expected by the 
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ROM Monitor for the serial port 1 download. The file must then be transferred to the board from the 
host. The baud rate is restored to 9600 so that terminal emulation support can function after the 
program has been downloaded, The ROM Monitor will wait for you to restore the baud rate (9600) and 
press Enter prior to executing the downloaded program. This prevents any program I/O from being 
lost or incorrectly displayed when it begins execution. 


The following is an example of what you might see when the program is allowed to run. 


Loaded successfully... 
Entry point at 0x25130... 


7.6.13 Cache Options 


Options A and B allow the user to enable or disable the processor’s instruction and data caches, 
respectively. These options toggle the status of the caches and take effect immediately upon 
selection. The current cache status is indicated at the end of each option and remains in effect upon 
exit from the ROM Monitor menu. 


7. ROM Monitor User Functions 


The ROM Monitor contains several functions that are available to user programs. The prototypes of 
these functions can be found in the usr_func.h file in the directory \osopen\m405_evb\include (for 
RS6000/SUN users the directory is /usr/osopen/m405_evb/include). These functions include: 


send_packet_on_bootdev() Allows an IP packet to be sent over the device that was used to 
load the application program (either the Ethernet or the second 
serial port, SP2). 


sh_register() Used to register a function that will be called when an IP packet is 
received by the ROM Monitor over the boot device. 

get_board_cfg() Reads the configuration data associated with the board. 

enet_send_macframe() Allows a frame to be sent over the Ethernet. 

enet_register() Allows the user to register an IP address for the Ethernet (an IP 


address different from that assigned to the ROM Monitor) and to 
specify a function to be called when a frame arrives for that 


address. 
enetisThere() Determines if the Ethernet chip is present on the board. 
enetinit() initializes the Ethernet. 
getchar() Reads one character at a time from the keyboard buffer over the 


first serial port (SP 1). 
s1putchar() Writes one character to the first serial port (SP1). 
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Applications must follow a predefined protocol to access ROM Monitor user functions. An example 
showing the proper calling procedures are included in the usr_samp.c sample program in the 
samples directory. This sample program calls the get_board_cfg() ROM Monitor function to 
determine the amount of DRAM installed on the board. This program will be run as a sample program 
in the next chapter. 


7.8 Flash Update Utility 


The openbios/flash directory contains all the code you need to reprogram the flash memory on the 
board. This utility takes a binary image file targeted for the ROM as input, and generates a loadable 
file that will reprogram the flash memory with the data in the binary input file. The file can then be 
loaded by an existing ROM Monitor version (which will be overwritten upon successful completion of 
the loaded program) or via RISCWatch JTAG. 


IMPORTANT: Please see the readme.txt file in the openbios/flash directory for important 
information regarding the use of this tool. 


Be aware that if you use the ROM Monitor bootp or the RISCWatch ROM Monitor mode download 
process to reprogram the flash, and the program loaded contains errors that will not allow you to 
download images in the same manner, your flash may be corrupted and rendered useless. In this 
case you will need to use RISCWatch JTAG or a ROM burner to reprogram the flash. 


RISCWatch JTAG users will find a RISCWatch command file, rw_flash.cmd in the openbios/flash 
directory. This command file can be used to prepare the board, load the flash update program 
containing the new binary image to program into the ROM, and start it running. This method can be 
used to program new flash parts, or to reprogram a corrupted flash part when normal ROM Monitor 
downloads are not possible or inconvenient. When using this command file, RISCWatch must be 
used in JTAG mode. 


7.9 Network Address of the Ethernet Controller 


The reference board’s 405GP Ethernet controller has been assigned a unique six-byte network 
address. This address, also known as the media access control or MAC address, may need to be 
known by customers using the board to develop their own ROM versions. 


The easiest way to obtain its value is to hook up a terminal (or terminal emulator) to the serial port 1 
(see Chapter 6.1, “Connecting the Reference Board to the Host”) and bring up the ROM Monitor. 
After selecting option 7 to display the configuration, the controller's network address is displayed in 
the Ethernet boot source’s hwadar field as twelve hex characters (six bytes). 


Another way to obtain the address, is to search the Vital Product Data (VPD) area in ROM where the 
network address is stored. The VPD fields consist of ASCII strings identifying the type of field, a 
length byte specifying the length of the associated data, and the data itself. The VPD begins at 
address OxFFFFFEOO and is marked by field ““VPD” with 0 bytes of associated data. The network 
address is marked by ““NA’” with six bytes of associated data (the network address). Finally, the end 
of the VPD is marked with ““END”. To extract the network address, a program would typically start at 
address OxFFFFFEOO, scan for “*NA”, verify the next byte is 0x6, and treat the next six bytes as the 
network address. 
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Chapter 8. Sample Applications 


This chapter describes the steps necessary to build and run the sample programs included in the 
PPC405GP design kit software support package. This code includes a limited version of IBM’s OS 
Open real time operating system and is separate from the ROM Monitor code described in Chapter 7. 


8.1 Overview 


The sample application programs are compiled, assembled, and linked using the IBM High C/C++ 
compiler, assembler, and linker. OS Open libraries are used during the link step to create an 
executable file in ELF format. This file includes the OS Open bootstrap code as well as other OS 
Open functions and is referred to as a boot file. One of the tools provided in the software support 
package, eimgbld, is then used to convert the boot file into the format used by the ROM Monitor to 
load programs onto the evaluation board (see Appendix B for more information on the ROM Monitor 
load format). The output of the eimgbld step is a file referred to as a boot image file. 


There are several ways to load and execute a boot image file. One way is to use the ROM Monitor to 
load and execute the file. Network loads over Ethernet or SLIP require that the host contain the bootp 
and tftp servers and be properly configured to support the bootp and tftp protocols (see the previous 
chapters on host configuration and ROM Monitor setup). Loads over serial port 1 require a terminal 
emulator that supports the kermit transfer protocol. A ROM Monitor load is initiated via option 0 from 
the ROM Monitor main menu. 


Another way to load and execute the boot image file is to use the RISCWatch debugger in ROM 
monitor mode. To bring up RISCWatch in ROM Monitor mode (see the RiISCWatch Debugger User's 
Guide for details), you must update the RISCWatch environment file for ROM Monitor 
communications, enable the ROM Monitor debugger (via option 5), exit the ROM Monitor menu (via 
option 0) and then start up RISCWatch on the host system. The RISCWatch load image command 
can then be used to load the boot image file onto the board. Once loaded successfully, the program 
can be debugged and/or executed. At any time the RISCWatch logoff command can be issued to 
execute the program. This command tells the ROM Monitor to exit debug mode and start the 
execution of the program. After program execution, users should quit and restart RISCWatch before 
loading another boot image file to run. Without quitting RISCWatch, subsequent boot image execution 
can not be guaranteed. 


Note: RISCWatch also provides the means to load a boot file (as opposed to a boot image file) via its 
load file command. See the “Running Your Programs” section in the RiISCWatch Debugger User's 
Guide for additional information. This section also describes the steps required to load and debug 
boot and boot image files. 


8.2 ROM Monitor Flash Image 


The flash memory on the board comes preprogrammed with a specific version of the ROM Monitor. 
This version may not be latest version of the ROM Monitor. To run the samples in the software support 
package, the latest version should be used. The latest version of the ROM Monitor is included in the 
software support package in the file: 


\osopen\m405_evb\openbios\lib\rom_***.img (PC) 
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/usr/osopen/m405_evb/openbios/lib/rom_***.img (RS6K & SUN) 


where *** is equal to the ROM Monitor version. If the *** version number of the ROM Monitor in the 
software support package does not match the version number displayed by the monitor when it 
comes up on the board, you can load the more recent version of the monitor provided in the software 
support package to re-program the flash memory. 


The rom_***.img file can be loaded using the ROM Monitor or the RISCWatch debugger. For it to 
load properly upon the selection of ROM Monitor option 0, it must be copied to boot.img if the 
suggested bootptab entry was used (see “Configuration of bootp and tftp to Support ROM Monitor 
Loads” on page 7-2). 


To load using RISCWatch, enable the ROM Monitor debugger (via option 5), exit the ROM Monitor 
menu (via option 0), start RISCWatch on the host system (make sure the RISCWatch environment file 
is setup for ROM Monitor communications), then use the following RISC Watch commands to load and 
execute the rom_***.img image file: 


load image \osopen\m405_evb\openbios\lib\rom_***.img (PC) 
load image /usr/osopen/m405_evb/openbios/lib/rom_*** .img (RS6K & SUN) 


logoff 


You will see screen information similar to that shown below. Lines preceded by “$$” are annotation for 
this example and do not appear on the screen. 


$$ Standard ROM Monitor load screen below 
PPC405GP 1.2 ROM Monitor (11/6/99) 
$$ Version 1.2 already installed corresponds to rom_12.img 


SHSSSssHsSessnsSsTHses SYStém Into -SS=Hs=$SssRSSSHHSss= 


Processor = AO5GP, PVR: 40110000 
Processor speed = 200 MHz 
PLB Bus speed = 100MHz 
Ext Bus speed = 50 MHz 
PCI Bus speed = 33 MHz 
Amount of SDRAM = 16 MB (Bank 1 Enabled) 


External PCI arbiter enabled 
--- Device Configuration --- 
Power-On Test Devices: 
000 Disabled System Memory [RAM] 
001 Disabled Ethernet [ENET] 
004 Disabled Serial Port 2 [S2] 


Boot Sources: 
001 Enabled Ethernet [ENET] 
local=7.1.1.5 remote=7.1.1.4 hwaddr=1000abcdef55 
004 Disabled Serial Port 2 [S2] 
local=8.1.1.5 remote=8.1.1.4 hwaddr=fffffffffffFf 
005 Disabled Serial Port 1 [S1] 
Baud=38400 
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Debugger: Disabled 


1 - Enable/disable tests 
2 - Enable/disable boot devices 
3 - Change IP addresses 
4 - Ping test 
5 - Toggle ROM monitor debugger 
6 - Toggle automatic menu 
7 - Display configuration 
8 - Save changes to configuration 
9 - Set baud rate for sl boot 
A - Enable/disable I cache (Enabled) 
B - Enable/disable D cache (Enabled) 
0 - Exit menu and continue 
->0 


$$ Selection of 0 causes evaluation board to be loaded. Previous 
$$ arrangements must have been made to place the new ROM Monitor 
$$ image (for ex. \osopen\m405_evb\openbios\lib\rom_13.img) in the 
$$ place where bootp expects to find it (for ex. boot.img) 

Booting from [ENET] Ethernet... 

Sending bootp request 


Loading file “\osopen\m405_evb\samples\boot.img” 
Sending tftp boot request 

Transfer Complete 

Loaded successfully 

Entry point at 0x25028 


$$ following information is from the ROM Monitor update program 
HHH EEE IBM 405GP Evaluation Kit FLASH Update ######tt### tt tt # 
ROM Monitor Version 1.3 


$$ Heed the following warning. The ROM Monitor image could be 
$$ rendered unusable and the board useless until the flash ROM is 
$$ replaced. 
WARNING: You are about to re-program your ROM Monitor FLASH 
image. Do NOT turn off power or press reset 
until this procedure is completed. Otherwise 
the card may be permanently damaged!!! 


Do you wish to continue? (y or n)y 


Verifying new FLASH Image... 
131072 matches, O mismatches 


Update complete! 
All done! 


After the update completes, a reset of the board should display the menu of the new ROM Monitor 
version. 
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8.3. Using the Software Samples 


The sample application programs are in \osopen\m405_evb\samples (for RS6K & SUN the directory 
is /usr/osopen/m405_evb/samples). It is recommended that users first build and run the Dhrystone, 
usr_samp, and timesamp sample programs as detailed below, to become familiar with the working 

environment. These sample programs use basic_os.c to provide a minimal OS Open configuration. 


Additional details regarding the sample programs and application development in general can be 
found in the “Developing OS Open Applications” chapter in the /BM OS Open User's Guide. That 
chapter should be referenced for instructions on building and running the applprog, benchmk, 
mailsamp, and cat sample programs. 


The sample makefile contains the directives needed to build all the sample programs. It is suggested 
that this makefile be used as the starting point for building subsequent user applications. 


Before attempting to build the samples, ensure the osopen/bin directory and the directory that 
contains the compiler, are part of your execution path (these steps should be modified accordingly 
based on where the compiler and the software support package were actually installed). 


For PC hosts: 
1. Edit AUTOEXEC.BAT using an editor such as e (you should back this file up before editing). 
2. If the following statement is missing, add it to the end of the file. 
SET PATH=C:\highcppc\bin;C:\osopen\bin; $PATH%; 
3. Run AUTOEXEC.BAT to update your path. 
For RS/6000 and SUN hosts: 
1. Issue the command: 
export PATH=SPATH:/usr/osopen/bin:/usr/highcppc/bin 
OR (to update your PATH permanently): 
1. Edit ~/.profile using an editor such as vi. 


2. Add PATH=SPATH: /usr/osopen/bin: /usr/highcppc/bin as a line in your profile before the 
line “export PATH”. 


3. Run . ~/.profile to update your profile. 


Note: The "make" utility supplied with the PC version of the kit may not run under a Windows NT 
command prompt that is started by cmd.exe. To avoid potential problems, start a DOS 
command prompt using the command COMMAND.COM and compile from there. Also, some 
Windows 95/98 users may receive a “Program Requires MS-DOS Mode” pop-up message 
when compiling. To prevent this annoying message from occurring, select ‘Properties’ for the 
MS-DOS window you are compiling from, then select Advanced and ensure that the ‘Suggest 
MS-DOS mode as necessary’ box is not checked. 


8.3.1. Building and Running the Dhrystone Benchmark 


The Dhrystone benchmark is a commonly available integer benchmark. Since the main loop of this 
benchmark fits into the caches of many processors, its validity as a predictor of system performance 
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may be suspect. It is included here as an example of an application to be built, loaded onto the 
evaluation board, and executed. 


To build the Dhrystone benchmark, enter the command make dhry from the command line while in 
the samples directory. The makefile will compile the Dhrystone source files, link the resulting object 
files with the support libraries, and produce the boot file, dhry, and the boot image file, dhry.img. 


If the bootptab entry suggested in Chapter 4, “Host Configuration,” was used, then dhry.img must be 
renamed or copied to boot.img in order to be selected by the ROM Monitor load process. Select 
option 0 from the ROM Monitor screen to load and run the image. 


To load using RISCWatch, enable the ROM Monitor debugger (via option 5), exit the ROM Monitor 
menu (via option 0), start RISCWatch on the host system (make sure the RISCWatch environment file 
is setup for ROM Monitor communications), then use the RISCWatch load image command to load 
the dhry.img file. Once successfully loaded, the logoff command can be issued to execute the 
program. 


You should see the following messages (or ones like them) appear on the ROM monitor screen. 
Explanations enclosed by () do not appear on the screen but are added here as clarification. 


Booting from [ENET] Ethernet... 
Sending bootp request... 


(This requests the Host workstation to return the name of the boot image.) 


Loading file “\osopen\m405_evb\samples\boot.img”... 
Sending tftp boot request... 


(Having obtained the file name, the ROM monitor uses tftp to retrieve the file from the host 
workstation.) 


Transfer Complete... 
Loaded successfully... 
Entry point at 0x25al18... 


(Having loaded an image, the ROM monitor is now transferring control to the application. Subsequent 
messages are from the application.) 


Dhrystone Benchmark, Version 2.1 (Language: C) 
Program compiled without ‘register’ attribute 
Please give the number of runs through the benchmark: 


At this point, enter the number of desired iterations. The test is designed not to give results if the 
selected iterations completes in less two seconds, so pick a large number (= 1000000). After the test 
completes, a check screen will be displayed, followed by the benchmark results. The results may vary 
based on the system environment. 


8.3.2 Building and Running the usr_samp Program 


The usr_samp.c program is included as a sample to be built and run on the EVB. It’s a simple 
program that shows how to properly call the get_board_cfg() ROM Monitor user function to determine 
the ROM Monitor version, the amount of DRAM installed on the board and the Ethernet controller’s 
MAC address. Developers interested in using any of the ROM Monitor user functions should use this 
program as a guide. 
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To build the usr_samp program, enter the command make usr_samp from the command line while in 
the samples directory. The makefile will compile the usr_samp..c file, link the resulting object file with 
the support libraries, and produce the boot file, usr_samp, and the boot image file, usr_samp.img. 


If the suggested bootptab was used, then usr_samp.img must be renamed or copied to boot.img in 
order to be selected by the ROM Monitor load process.Select option 0 from the ROM Monitor screen 
to load and run the image. 


To load using RISCWatch, enable the ROM Monitor debugger (via option 5), exit the ROM Monitor 
menu (via option 0), start RISCWatch on the host system (make sure the RISCWatch environment file 
is setup for ROM Monitor communications), then use the RISCWatch load image command to load 
the usr_samp.img file. Once successfully loaded, the logoff command can be issued to execute the 
program. 


You should see the following messages (or ones like them) appear on the ROM Monitor screen. 


Booting from [ENET] Ethernet... 
Sending bootp request... 


Loading file “\osopen\m405_evb\samples\boot.img”... 
Sending tftp boot request... 

Transfer Complete... 

Loaded successfully... 

Entry point at 0x25e48... 


Hello 405GP user! 
Your ROM Monitor version is: 1.3 


Your 405GP Evaluation Board has 16777216 bytes of DRAM installed. 


Your Ethernet controller’s network address is: 1000abcdef55 


usr_samp done! 


The DRAM amount listed should match the amount installed on the board. 


8.3.3 Building and Running the timesamp Program 


The timesamp.c program is included as a sample to be built and run on the EVB. This program is an 
example of how to properly time a particular function or benchmark. The user must know and define 
the time base frequency (the number of times the time base register is updated per second) in the 
timesamp.c to ensure the timing calculations are accurate. 


To build the timesamp program, enter the command make timesamp from the command line while in 
the samples directory. The makefile will compile the timesamp.c file, link the resulting object file with 
the support libraries, and produce the boot file, timesamp, and the boot image file, timesamp.img. 


If the suggested bootptab was used, then timesamp.img must be renamed or copied to boot.img in 
order to be selected by the ROM Monitor load process. Select option 0 from the ROM Monitor screen 
to load and run the image. 
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To load using RISCWatch, enable the ROM Monitor debugger (via option 5), exit the ROM Monitor 
menu (via option 0), start RISCWatch on the host system (make sure the RISCWatch environment file 
is setup for ROM Monitor communications), then use the RISCWatch load image command to load 
the timesamp.img file. Once successfully loaded, the logoff command can be issued to execute the 
program. 


You should see the following messages (or ones like them) appear on the ROM Monitor screen. 


Booting from [ENET] Ethernet... 
Sending bootp request... 


Loading file “\osopen\m405_evb\samples\boot.img”... 
Sending tftp boot request... 

Transfer Complete... 

Loaded successfully... 

Entry point at 0x25e48... 


Please give the number of runs through the benchmark: 


At this point, enter the desired number of runs through the function or benchmark being timed. In this 
sample, the function being timed should execute for approximately a second, so a number between 1 
and 10 would suffice. 


8.3.4 Setting the time in the on-board clock 


The battery-backed clock can be synchronised to real (wall-clock) time. A sample function to do this is 
provided in the samples file utils.c. The function set_time_once_only() requires that you edit its 
source code to provide the current time and date infomation. We suggest that you enter a time which 
is a couple of minutes into the future, to give you time to finish editing the file, recompile, link and 
download it onto the evaluation board. When the wall-clock time reaches the time that you set in the 
source code, run the function. This is a one-time only effort, as the battery will ensure that the clock 
remains set even when power is removed from the board. 


8.3.5 PPC405 MAC instruction sample 


This sample program demonstrates the performance advantage of the 405 MAC 
(multiply/accumulate) instructions for common DSP operations. It is built in to the applprog sample 
image. Refer to the OS Open User's Guide for more information on building applprog. 


The easiest way to use the program is to call it from the OpenShell prompt as “macsamp()”. It will then 
use standard input and output for the prompts and responses. No file system is required for the basic 
operation of the program, but if it is desirable to save the outputs, around 250 Kbytes of space is 
required in the current directory. 


First, the program generates a 3 second sample data stream in storage. The sample consists of three 
sine waves (625, 1250, and 3750 Hz) sampled at 20 KHz using 16-bit signed samples. The program 
then allows the user to select one of two filter implementations, one using the MAC instructions and 
another one using the same underlying logic, but implemented using only basic PowerPC 
instructions. The filter is a 60th order lowpass FIR filter with a stopband gain of -70 db, passband 
edge at 1.5 KHz, and stopband edge at 3.0 KHz. The filter coefficients were calculated using the 
programs supplied with “Analog and Digital Filter Design using C” by Les Thede (Prentice Hall ISBN 
0-13-352627-5). This book is an excellent reference in understanding the logic of the filter itself. 
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The cycle count (as derived from timebase values) for the filter operation is displayed, so by running 
the program twice, selecting each filter, the performance benefit of the MAC instructions is shown. 
The program also allows the original sample and the filter output to be saved as .WAV files, if a local 
file system exists. Curious users can transfer the files via FTP to a PC and hear the audible difference 
the lowpass filter makes. Shown below are frequency domain plots of the generated input sample and 
the filtered output. 
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The 3 sine waves are clearly shown in the input sample as being equal amplitude. 
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The output sample shows the first two sine waves virtually unchanged, but the signal at 3750 Hz has 
been significantly attenuated, as you would expect for the lowpass roll off beginning at 1.5 KHz. You 
can also see some amplitude ripples in the transition zone as a result of the filter method used. 


8.4 Resolving Execution Problems 
Configuration errors in the network or bootp tables cause most of the problems with running the 


sample applications. This section contains information that will aid users in identifying common 
problems. 
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8.4.1. Using the Ping Test on the ROM Monitor to Verify Connectivity 


If the ping test fails, verify that TCP/IP is running on the host system and that the IP addresses on the 
selected interface are correct. The local address refers to the IP address of the evaluation board, and 
the remote refers to the host workstation address. The host workstation address must match the one 
selected during configuration of the host network interface. Also consult your TCP/IP documentation 
to insure proper network configuration. 


8.4.2 Setup of bootp and tftp Servers (Daemons) for ROM Monitor Loads 


Insure that the bootp and tftp servers are started on the host workstation. If possible, use the tftp 
command from another workstation to retrieve the load image. If this fails, make sure the image exists 
in the target directory and that it is readable by “others”. If the tftp transfer succeeds, check the 
bootptab entry in the bootptab file to insure that it specifies the correct interface and IP address of 
the evaluation board. 


8.5 Using OS Open Functions 


OS Open provides the following major classes of functions for the embedded programming 
environment: 


* Thread management 


The unit of execution context for OS Open is the thread as defined by POSIX standards. Functions 
are provided to create threads with various scheduling and execution attributes. To manage the 
execution environment, serialization and synchronization primitives are part of OS Open. The 
system also provides functions to associate data with specific threads. 


* Storage management 


OS Open supports variable block allocations in the form of a heap. Functions are provided to 
extend the heap, query heap usage, and allocate storage to meet alignment constraints. OS Open 
also provides an independent storage management mechanism to allocate fixed blocks of storage 
in constant time. 


¢ Interrupt and fault support 


OS Open provides functions to attach user-written code to any of the processor exceptions and 
interrupts. Most of the functions of OS Open can be used in these interrupt handlers, except for 
those functions that suspend execution or are valid only in the context of an executing thread. 
When the underlying hardware platforms support it, OS Open platform-specific libraries provide 
additional functions to attach user-written code to external interrupts supported on the platforms. 


* Clock and timer management 


OS Open functions provide time-of-day clock support and the ability to create, use, and destroy 
timers. These timers can be one-time or periodic. 


¢ Device support 


OS Open functions support the installation of user-written device drivers to provide character 
special files, block special files, and logical file systems. Low-level POSIX I/O (read, write) as well 
as ANSI C stream (fget, fout) functions are provided for device and regular file access. 


¢ ANSI C library support 
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OS Open provides a comprehensive set of ANSI C functions, providing support for string 
manipulation, memory management, string-to-number conversion, input/output, non-local jumps, 
and variable arguments. 


¢ Pseudo device driver support 


OS Open provides several functions, such as TTY and DOS file system functions, that are installed 
and managed like device drivers, but they do not manipulate actual hardware nor do they have 
platform or device dependencies. 


OS Open provides functions that create and manage TCP/IP sockets. Network interface functions 
for Token Ring, Ethernet, and Serial Line Interface Protocol (SLIP) are also provided. With the 
TCP/IP protocol stack and network interfaces, additional functions are provided that implement 
several popular networking utilities, such as ping, ifconfig, ftp, and telnet. 


¢ Debug functions and kernel abstract data types 


OS Open provides functions that set, clear, and query break points. OS Open features an internal 
circular trace buffer for operating system and user events. Also, functions are provided that dump 
kernel data objects in a readable form. 


Additional information can be found in the OS Open’s User’s Guide. 
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Chapter 9. Application Libraries and Tools 


This chapter describes some of the application libraries and tools available in the PPC405GP design 
kit board support software package. See the OS Open User’s Guide and Programmer’s Reference for 
additional information. 


9.1 OS Open Libraries 


The OS Open operating system is composed of a real-time executive and optional libraries of 
functions and macros. 


The real-time executive provides a operating system core for embedded applications. Depending on 
an application’s requirements, an embedded application may also incorporate one or more optional 
libraries. 


This modular approach enables embedded system developers to scale an OS Open operating 
system to match their application requirements. Because unneeded features are not present, an OS 
Open configuration can provide savings in system hardware, initialization and reset time, and 
program size. 


Table 9-1 summarizes the OS Open libraries, described in the OS Open User's Guide and in this 
user’s guide. For detailed descriptions of the OS Open functions and macros, refer to the OS Open 
Programmer's Reference. 


Table 9-1. OS Open Libraries 


Library File Name Platforms 
Alignment Exception Support Library alignLib.a Common 
ANSI C Library cLib.a Common 


ANSI C Math Library mathLib.a Common 


ANSI C I/O Library fsLib.a Common 
Bios Ethernet Library benetLib.a PPC405GP 


Block Buffer Library bbuffLib.a Common 


Block Library bIkLib.a Common 


Extended Heap Library heapLib.a Common 


Boot Library(DRAM) bootlLib.a PPC405GP 


C++ runtime support (High Gia” support) Library | cppLib.a, crti.o, ELF 
crtn.o,mwdctorl. 
fo) 


Card Services/enabler software layer for PCMCIA | csLib.a Common 
support 
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Table 9-1. OS Open Libraries (Continued) 


Library File Name Platforms 
Clock Support Library and NV-RAM clockLib.a PPC405GP 
Debug Support Library dbLib.a Common 
Device and File Support Library devLib.a Common 
DOS File System Support Library fatLib.a Common 
Dynamic Loader Library IdrLib.a Common 
Ethernet Support Library enetLib.a PPC405GP 
File Transfer Protocol Support Library ftpLib.a Common 
Floating Point Library fpeLib.a Common 
I2C Library PPC405GP 
Input/output Support Library ioLib.a PPC405GP 
Kernel Abstract Data Types Library kadtLib.a Common 
Keyboard/Mouse Controller Library keybLib.a PPC405GP 
Network Support Library netLib.a Common 
NFS Support Library nfsLib.a Common 
On-Chip Memory Support Library ocmLib.a PPC405GP 
OpenShell shell.o Common 
PCI Library pciLib.a PPC405GP 
PCMCIA ATA/IDE Hard disk device driver pataLib.a Common 
PowerPC Low Level Access Support Library ppcLib.a PPC405GP 
Queue Library queLib.a Common 
RAM Disk Library ramdLib.a Common 
Rate Monotonic Scheduling (RMS) Library rmsLib.a Common 
Remote Source Level Debug Library rsldLib.a Common 
Ring Buffer Library rngLib.a Common 
RPC Support Library rpcLib.a Common 
Runtime Library runlib.a Common 
SCSI Support Library scsiLib.a Common 
Serial Support Library asyncLib.a PPC405GP 
Socket Services for PCMCIA support Common 
Symbol Support Library symLib.a Common 
TCP/IP Protocol Support Library tcpipLib.a Common 
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Table 9-1. OS Open Libraries (Continued) 


Library File Name Platforms 

Telnet Daemon Support Library Common 
Telnet Client Support Library telnet.o Common 
The Real-time Executive rtx.o, rtxLib.a Common 
OS Open Minimal Kernel rtxmin.o Common 
OS Open Kernel Extensions for the minimal Common 
kernel 

Timer Tick Support tickLib.a PPC405GP 
Trivial File Transfer Protocol tftp.o Common 
TTY Support Library ttyLib.a Common 
VGA Display Library PPC405GP 


The real-time executive, the only required component in an OS Open operating system, provides a 


full set of basic operating system services: 


* Thread management 


¢ Virtual memory management for OS Open with Virtual Memory 


* Storage management 

* Signals 

* Clocks and timers 

¢ Interrupt and fault handling 
*« Message queues 

* Semaphores 

¢ Trace buffer support 

¢ Miscellaneous services 


The C functions for the real-time executive functions are in two libraries, rtx.o and rtxLib.a. The rtx.o 
library contains the OS Open real-time executive. The rtxLib.a library contains interface routines to 
OS Open functions, and is linked with application programs to resolve calls to the real-time executive. 


9.2 Using Libraries and Support Software 


The object libraries specific to the reference board are described below. 


Table 9-2. OS Open Libraries for the Reference Board Platform 


Boot Library(RAM) 


I2C Library 


Library 


Ethernet Device Driver Support Library 


File Name 
bootlLib.a 
enetLib.a 


i2cLib.a 
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Table 9-2. OS Open Libraries for the Reference Board Platform 


Library File Name 
Input/Output Support Library ioLib.a 
Keyboard/mouse Controller Library keybLib.a 
PowerPC Low Level Access Support Library ppcLib.a 
Real-time Clock Interface Support Library clockLib.a 
ROM Monitor Ethernet Interface Library benetLib.a 
Serial Support Library asyncLib.a 
Software Timer Tick Support Library tickLib.a 


9.2.1. Serial Port Support Library 


This library supports the serial ports on the reference board. Use in conjunction with the function 
provided by devLib.a and fsLib.a to provide a high level I/O interface to application programs. The 
serial port support functions reside in the asyncLib.a library. 


9.2.2 Boot Library (RAM) 


This library contains the OS Open bootstrap program for the appropriate platform. The boot library 
performs initial processing to prepare the completed application program for execution on the board. 
For the reference board platform, this processing includes moving the loaded program such that real 
addresses correspond with addresses assumed by the language development tools. The boot library 
for the reference board platform also dynamically determines available heap space and prepares the 
symbol table for use by OS Open symbol management routines. The boot library does not export any 
functions. 


9.2.3. Input/Output Support Library 


The input/output functions reside in the ioLib.a library. To initialize the I/O subsystem, you must call 
ioLib_init() (normal mode) or dbg_ioLib_init() (ROM Monitor debug/ethernet) before performing any 
I/O other function. 


9.2.4 Keyboard/Mouse Controller Support Library 


This library supports the keyboard and mouse ports on the reference board. The keyboard support 
includes a basic translation function which converts keystokes to VT100 sequences, and allows the 
keyboard to be attached to the TTY driver in ttyLib.a. This allows it to be used as the stdin device for 
OS Open. The mouse driver presents the raw scancodes from the mouse to the application program. 
The keyboard and mouse controller functions reside in keybLib.a. 


9.2.5 1I2C Library 


This library supports reads and writes to devices on the I?C bus. It also provides functions to directly 
access the I°C registers. The IC library functions are in i2cLib.a. 
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9.2.6 PowerPC Low-Level Processor Access Support Library 


The low-level access support library contains C-callable versions of the special PowerPC instructions. 
A few of the sample programs use these functions to manipulate the PPC405GP’s special registers. 
These functions provide access to processor instructions not generated by compilers. For example, 
device drivers often have a requirement to control data caching, disable interrupts, synchronize I/O, 
and other processor and platform-specific operations. The low-level access support functions reside 
in the ppcLib.a library. 


9.2.7. ROM Monitor Ethernet IP Interface Library 


This library contains routines allowing access to the ROM Monitor’s Ethernet IP interface. These 
functions allow the Ethernet to be simply configured with a unique IP address for use with TCP/IP 
functions. The ROM Monitor Ethernet IP Interface functions reside in benetLib.a library. The 
benetLib.a functions are only available with OS Open without Virtual Memory. 


9.2.8 Real-time Clock Interface Support Library 


This library contains routines to read and set the reference board's battery-backed real-time clock. 
These functions are not to be confused with the real-time clock functions provided directly by OS 
Open when the system is running. The real-time clock interface support functions reside in the OS 
Open’s clockLib.a library and are available to perform the following features: 

¢ Set the OS Open clock from the real-time clock. 

¢ Set the real-time clock from user-supplied data. 

¢ Read and write NV-RAM in the clock chip. 


A sample function to set the battery-backed clock to wall-clock time is provide. See “Setting the time 
in the on-board clock” on page 8-7 for more information. 


9.2.9 Ethernet Device Driver Support Library 
This library provides support for the ethernet on the PPC405GP. The Ethernet device driver support 
functions reside in the enetLib.a library. 


9.2.10 Software Timer Tick Support Library 


The OS Open system requires a periodic call to timertick_notify() to maintain internal clocks and 
timer functions. The tickLib.a library contains an implementation of the timertick_notify() function 
for PowerPC architecture machines. Timer tick support functions reside in the tickLib.a library. 


9.3. Device Drivers Supplied with the Board Support Software 


Device drivers provided with the reference board support package include: 


¢ Asynchronous 
« Ethernet 

¢ 12C 

« Keyboard/mouse 
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Examples and references are provided where appropriate. Users should also refer to the 
samples/thread0.c file for driver installation examples. Source code for each of the drivers is included 
in subdirectories under the samples directory. 


For more information about any of the OS Open functions mentioned in this chapter, refer to the OS 
Open Programmer's Reference. 


9.3.1 Asynchronous Device Driver 


The asynchronous device driver supports the asynchronous communication ports found on the 
reference board. Following is a brief functional description of the device driver: 

¢ Support from 50 baud 

¢ Full duplex modem line control discipline 

¢ Overrun error, parity error, and framing error detection 

¢ BREAK interrupt detection 

¢ Support for data length of 5, 6, 7, and 8 bits 

¢ Support for 1, 1.5 and 2 stop bits 

¢ Support for receive and transmit parity 

¢ Support for odd and even parity 

¢ Support for transmitting BREAK 

¢ Support for 16 byte FIFO in the universal asynchronous receiver transmitter (UART) 

¢ Programmed I/O (PIO) interrupt-driven slave communication 

¢ Interrupt driven input/output 

¢ Polled output functions 

Since only full duplex modem line control discipline is supported, connection between the 
asynchronous port and another device must be made through a NULL modem. A NULL modem is a 


device that crosses transmitted data and received data pins to enable communication. The only time 
a NULL modem is not necessary is when connection is made to a real modem device. 


Refer to the OS Open sample file thread0.c for an example of installing the asynchronous device 
driver and to samples/asyncLib for the driver source code. 
9.3.1.1. Device Driver Installation 


The asynchronous device driver is installed by calling driver_install(). Following is an example of 
asynchronous device driver installation. 


#include <sys/asyncLib.h> 

#include <ppcLib.h> 

int devhandle; 
rce=driver_install(&devhandle, async_init); 


async_init() is declared in the file <sys/asyncLib.h> as follows. 
int async_init (driver_t *dsw, va_list vargs) 


Upon successful installation, driver_install() returns 0; otherwise —1 is returned. For more 
information on driver_install(), refer to the OS Open Programmer's Reference. 
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9.3.1.2 Device Installation 


After the asynchronous device driver is installed, named devices can be created using 
device_install(). Following is an example of device installation. 


rc=device_install("/dev/s0", CHRTYPE, devhandle, 1, 1024, 


EXT_IRQ_COM1) ; 


1024,asyncClockRate, UARTO_BASE_ ADDRESS, CPCO_CRO_UARTO_EXTCLOCK_EN, 


For device installation, devhandle is the value obtained from the driver_install(). Device type 
CHRTYPE is defined in <sys/devDrivr.h>. 


Additional parameters passed in the device_install() call are as follows. 


Table 9-3. Additional Parameters Passed to driver_install() 


Parameter 
Fourth Parameter 
Fifth Parameter 


Sixth Parameter 


Meaning 
Port number to be installed (1 or 2) 
Size of write buffer 


Size of read buffer 


Seventh Parameter 


Input clock for the divisor (value defined in ppcLib.h) 


Eight Parameter 
Ninth Parameter 


Tenth Parameter 


UART base register address (from ppcLib.h) 
UART-relevent bits to be set in the CPCO_CRO register 
Interrupt IRQ_MIN < event <IRQ_MAX (from ioLib.h) 


Note 1: These are positional parameters. 


Note 2: Write and read buffer sizes indicate number of characters that can be 
buffered in the device driver. 


Upon successful installation, device_install() returns 0; otherwise —1 is returned. When the device is 
installed, error reporting for the device is turned off and xon/xoff pacing is enabled. For more 
information on device_install(), refer to the OS Open Programmer's Reference. 


9.3.1.3. Opening Asynchronous Communication Ports 


After the device is installed, the open() system call can be used to open a particular device. Following 
is an example of the open() system call used against the asynchronous port. 


fdl=open("/dev/s0", O_RDWR, asyncParityNone, asyncParityOdd, 


asyncStopBits1, 
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Additional parameters passed in open() are as follows. 


Table 9-4. Additional Parameters Passed to open() 


First Parameter Check/generate parity flag. Valid values are: asyncParityNone and 
asyncParityGen_Check 


Second Parity type. Valid values are asyncParityEven and asyncParityOdd. Because 
Parameter parameters are positional, this parameter must be specified even if parity is not used. 


Third Parameter Number of stop bits. Valid values are asyncStopBits1 and asyncStopBits2. 


Fourth Parameter | Data length. Valid values are asyncDataBits5, asyncDataBits6, asyncDataBits7, and 
asyncDataBits8. 


Fifth Parameter Baud rate. Valid values range from 50 baud. 


Note: These are positional parameters. All parameter constants can be found in <sys/ioctl.h>. 


Note: The oflag parameter, O_RDWR in this example, which is passed in the open call, is ignored by 
the device driver. When successful, open() returns a file descriptor, otherwise —1 is returned. 
open() can be called multiple times against the same asynchronous port. Communication 
parameters passed during the last open() call are set in the asynchronous port. For more 
information on open(), refer to the OS Open Programmer's Reference. 


9.3.1.4 Reading and Writing 


After successfully installing and opening the asynchronous port, read() and write() calls can be 
issued against that port. Multiple threads can issue read() and write() calls to the same port at the 
same time. However, simultaneous read() calls issued to the same port may block or be processed in 
an unexpected order. For these instances, thread scheduling and synchronization must be handled by 
the application. 


Following is an example of read() and write() calls. 


re=write(fd1,"\nOS Open Real-time Executive\n", 29); 
rc=read(fdl, buffer, 10); 


fd7 is the value obtained from the open() call. 


Note: For more information on read() and write(), refer to the OS Open Programmer's Reference. 
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9.3.1.5 I/O Control 


An ioctl() call issued against asynchronous device driver accepts the commands listed in Table 9-5. 
All parameter constants can be found in <sys/ioctl.h>. 


Table 9-5. ioctl() Commands for Asynchronous Device Drivers 


Command Parameters Explanation 
ASYNCBAUDSET Value from 50 Sets baud rate 
ASYNCBAUDGET Pointer to integer Returns baud rate 


ASYNCTRIGSET 


asyncFifoTrigger1, 
asyncFifoTrigger4, 
asyncFifoTrigger8, 
asyncFifoTrigger14 


Sets FIFO trigger level for asynchronous port 


ASYNCTRIGGET 


Pointer to integer 


Returns current trigger level 


ASYNCBREAKSET None Starts sending BREAK on port 

ASYNCBREAKCLR None Stops sending BREAK on port 

ASYNCSTICKGET Pointer to integer Returns the way the parity bit is interpreted by the port 

ASYNCSTICKZERO None Disables stick parity 

ASYNCSTICKONE None Parity interpretation tracks even/odd parity 

ASYNCRERRORGET Pointer to integer Returns and clears read error conditions. Values are 
defined in asyncLib.h 

ASYNCWERRORGET Pointer to integer Returns and clears write error conditions. Values are 
defined in asyncLib.h 

ASYNCERROREN None Enables error reporting 

ASYNCERRORDIS None Disables error reporting. All pending errors are cleared 


ASYNCERRORGET Pointer to integer Returns error reporting enabled flag 
ASYNCDLENGET Pointer to integer Returns current data length 
ASYNCDLENSET asyncDataBits5, Sets data length 

asyncDataBits6, 

asyncDataBits7, 

asyncDataBits8 
ASYNCSTOPGET Pointer to integer Returns number of stop bits 
ASYNCSTOPSET1 None Sets number of stop bits to 1 
ASYNCSTOPSET1_5 None Sets number of stop bits to 1.5 
ASYNCSTOPSET2 None Sets number of stop bits to 2 
ASYNGPARITYNONE None Disable parity 
ASYNCPARITYGEN None Enable parity 
ASYNGPARITYSGET Pointer to integer Return parity status (enabled/disabled) 
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Table 9-5. ioctl() Commands for Asynchronous Device Drivers (Continued) 


Command Parameters Explanation 
ASYNGPARITYODD None Sets parity to odd 
ASYNGPARITYEVEN None Sets parity to even 
ASYNCPARITYGET Pointer to integer Returns parity type 
ASYNCXONENABLE None Enables XON/XOFF flow control 
ASYNCXONDISABLE None Disables XON/XOFF flow control 
ASYNCXONGET Pointer to integer Returns XON/XOFF flow control status 
ASYNCMODEMSTAT Pointer to integer Returns modem status 
ASYNCFLUSHIN None Flushes input buffer 
ASYNCFLUSHOUT None Flushes output buffer 
ASYNCDRAIN None Blocks until all characters in output buffer have been 

transmitted 

ASYNCIGNBREAK None Ignores break interrupts 
ASYNCSIGBREAK None Sends SIGINT on reception of break condition 


ASYNCERRBREAK Returns error from read upon reception of break 


condition. 0x00 is placed in the receive buffer at the 
position where break occurred. 


Following is an example of an ioctl() call issued against an asynchronous device. 


rce=ioctl(fdl, ASYNCXONDISABLE) ; 
if (re !=0) printf(“ioctl failure\n”); 


fd7 is the value obtained from the open() call. 


9.3.1.6 Polled Asynchronous I/O 
A function is provided for polled output to s1 and s2 serial port. 


int sldbprintf (unsigned long uart_clock, unsigned char *base_reg, 
unsigned long chcr0O_reg, event_t int_level, const char *format, ...) 
int s2dbprintf (unsigned long uart_clock, unsigned char *base_reg, 
unsigned long chcr0O_reg, event_t int_level, const char *format, ...) 


The parameters passed to these functions are identical to printf() except for uart_clock, base_reg, 
chcr0_reg, and int_level. uart_clock specifies the clock speed, base_reg specifies the address of the 
base UART register, chcrO_reg specifies the bits in the CPCO_CRO register that are to be set (only 
the bits relevant to the UART are altered), and jnt_level specifies the external interrupt level. The 
same values used on the device_install() function may be used. See “Device Installation” on 

page 9-7. 


slbdprintf(asyncClockRate, UARTO_BASE ADDRESS, CPCO_CRO_UARTO_EXTCLOCK_EN, 
EXT_IRQ_COM1, “hello world\n\r”); 
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Because polled I/O transmits characters synchronously, these functions may be called from first level 
interrupt handlers (FLIHs) or a user-supplied panic function. Since the function waits until the 
characters are actually sent before returning, use of this with long strings can significantly affect the 
timing of calling programs. 


9.3.1.7 Flow control 


The s1 port is a full 16550-compatible implementation, and supports all 16550 lines, including CTS, 
RTS, DTR and DSR. 


However, the s2 serial port multiplexes the CTS/RTS and DTR/DSR hardware flow control signals 
onto the same pair of pins, so a choice must be made about which type of hardware flow control is to 
be used. This is implemented by setting bits in the CPCO_CRO register. If hardware flow control is 
desired, it should be set by setting flags in the chcrO_reg parameter that is passed to device_instal() 
when installing the s2 port device. The flags available are: 


* CPCO_CRO_UART1_CTS_RTS 
* CPCO_CRO_UART1_DTR_DSR 


One of these flags may be OR’d into any other values specified in the chcrO_reg parameter, as shown 
below: 


rc=device_install("/dev/s1", CHRTYPE, devhandle, 1, 128, 128, 
asyncClockRate, UART1_BASE_ADDRESS, 
CPCO_CRO_UART1_EXTCLOCK_EN | CPCO_CRO_UART1_CTS_RTS, EXT_IRQ_COM2); 


The device driver will automatically make sure that the selected signals appear on the correct pins on 
the s2 serial port connector, so that a normal serial connection can be made (no special cables 
required). The pin-switching is done via the on-board FPGA. 


If neither hardware flow control option is selected the status of the flow control pins is undefined, and 
only software flow control (KON/XOFF) should be used. 


9.3.2 Keyboard/Mouse Controller Driver 


The keyboard controller device driver supports the keyboard and mouse ports found on the reference 
board. Following is a brief functional description of the device driver: 


¢ Supports keyboard input 

¢ Supports raw input or translated keycodes 
¢ VT100 translation table installed as default 
¢ Setup to be stdin device by default 

¢ Mouse driver supports raw input 


Refer to the OS Open sample file io_init.c for an example of installing the keyboard device driver and 
to samples/keybLib for the driver source code. 


9.3.2.1. Device Driver Installation 


The keyboard controller device driver is installed by calling driver_install(). Following is an example 
of device driver installation. 


#include <sys/keyb.h> 
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#include <ppcLib.h> 
int kbdev; 
rce=driver_install(&kbdev, keyb_init); 


keyb_init() is declared in the file <sys/keyb.h> as follows. 

int keyb_init (driver_t *dsw, va_list vargs) 
Upon successful installation, driver_install() returns 0; otherwise —1 is returned. For more 
information on driver_install(), refer to the OS Open Programmer's Reference. 


9.3.2.2 Device Installation 


After the device driver is installed, named devices can be created using device_install(). Following is 
an example of device installation. 


rc=device_install("/dev/kb1", CHRTYPE, kbdev, 0, 128, 128, 
KEYB_BASE_ADDRESS); /* Install keyboard device */ 
rc=device_install("/dev/moul", CHRTYPE, kbdev, 1, 128, 128, 
KEYB_BASE ADDRESS); /* Install mouse device */ 


For device installation, kbdev is the value obtained from the driver_install(). Device type CHRTYPE 
is defined in <sys/devDrivr.h>. The mouse device driver is installed in the same manner as the 
keyboard driver, except that the fourth parameter, port number, is 1 instead of 0. 


Additional parameters passed in the device_install() call are as follows. 


Table 9-6. Additional Parameters Passed to driver_install() 


Parameter Meaning 


Fourth Parameter Port number to be installed (0 for keyboard, 1 for mouse) 


Fifth Parameter Size of read buffer 


Sixth Parameter Size of translated buffer 


Seventh Parameter Keyboard controller base address (from ppcLib.h) 


Note 1: These are positional parameters. 


Note 2: Read and translated buffer sizes indicate number of characters that can 
be buffered in the device driver. 


The read buffer holds scancodes from the keyboard before they are requested by a program. The 
translated buffer is used by the translation function when it converts scancodes into translated 
characters. 


Upon successful installation, device_install() returns 0; otherwise —1 is returned. For more 
information on device_install(), refer to the OS Open Programmer's Reference. 


9.3.2.3. Opening Keyboard Port 


After the device is installed, the open() system call can be used to open a particular device. Following 
is an example of the open() system call used against the keyboard port. 


fdl=open ("/dev/kb1", O_RDONLY) ; 
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However, a more typical use is to associate the keyboard with the TTY pseudo-device. In this case the 
keyboard driver is not opened directly, but is associated with the TTY device driver, and the open() is 
made against the tty device. 


#include <ttyLib.h> 

commd_t commdr = { (int (*) open, { (int)”/dev/kb1”,O_RDONLY} }; 

commd_t commdw = { /* values for some output device */ }; 

struct termios defaultattr = { /* initialise default term attributes */ }; 
int * tty_devh; 


driver_install(tty_devh, tty_init); 

device_install (“/dev/tty0”,DTYPE_TTY, *tty_devh, &commdr, &commdw, 
&defaultattr); 

fdl=open (“/dev/tty0”, O_RDONLY) ; 


The default translation table in the keyboard device driver translates keyboard scancodes to the 
VT100 escape sequences that the TTY device expects. This means that special keys (arrow keys, 
function keys etc.) appear the same as they would coming from a VT100 serial port terminal emulator, 
and the keyboard can be used as a direct replacement for the serial port as OS Open’s default input 
device. 


There is no default translation function for the mouse device driver - it returns the scancodes to the 
calling application. 


9.3.2.4 Reading 


After successfully installing and opening the keyboard port, read() calls can be issued against that 
port. Multiple threads can issue read() calls to the same port at the same time. However, 
simultaneous read() calls issued to the same port may block or be processed in an unexpected order. 
For these instances, thread scheduling and synchronization must be handled by the application. 


Note: For more information on read(), refer to the OS Open Programmer's Reference. 


9.3.2.5 I/O Controls 


Because the keyboard device appears to the TTY library as identical to an async serial-port device, it 
supports some of the async ioctl calls. These are: 

* ASYNCRERRORGET 

* ASYNCERROREN 

* ASYNCERRORDIS 

* ASYNCERROREN 

* ASYNCERRORGET 

* ASYNFLUSHIN 


These all function identically to the async device driver - see its description for more information. 


The keyboard driver also supports its own ioctl, which is described below. 
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9.3.2.6 Translation Function 


The default translation table for the keyboard device converts special keys, such as the function keys, 
to VT100 escape sequences which can be interpreted by the TTY library. It also handles routine 
keyboard matters such as: 


* converting scancodes to ASCII characters 

¢ handling the caps lock, scroll lock and num lock keys, including the keyboard LEDs 
¢ handling the shift and ctrl keys 

¢ handling the numeric keypad 


An ioctl function is available to substitute your own translation table, or to remove the translation 
function altogether and just return raw scancodes. The ioctl function is: 


* KEYBTRANSFUNCSET 
which takes as a parameter a function of type: 
¢ void (*)(char, void *) 


This function takes two parameters. The first is the scancode to be translated. The second parameter 
is really a pointer to a structure of type keybdds_t, which is defined in <sys/keyb.h>. This structure 
contains 2 ring buffers: the read ring buffer (rcv_ring) and the translated ring buffer 
(rcv_translated_ring). The sizes of these buffers are specified on the device_install() function call. It 
also contains many fields which your function can use to keep track of the keyboard state, such as the 
state of the caps lock, num lock or scroll lock keys. 


When a key is pressed, one or more scancodes are put into the read ring buffer. When a program 
requests a character from the keyboard device driver, the device driver extracts the scancode from 
the buffer and calls the translation function. The scancode is passed in as the first parameter and the 
pointer to the keybdds_t is the second parameter. The translation function should insert the translated 
key(s) into the translated ring buffer, which is part of the keybdds_t structure: 


void my_translate_function(char in_c, keybdds_t *dds) { 
char out_c; 


/* translation function converts scancode in_c to character out_c */ 
rngBufPut (dds->rcev_translated_ring,out_c,1); /* out_c into ring buffer */ 


If the translation function determines that the scancode(s) must be translated into more than one 
output character (for example, an arrow key is converted into a escape sequence such as “ESC [ A’), 
it may place all of the translated characters into the translated buffer (rcv_translated_ring). When a 
program subsequently performs a read from the keyboard device driver, the device driver will extract 
the characters from the translated buffer and pass them back to the calling program (without looking 
for further scan codes in the read buffer, and without calling the translation function again). When the 
translated buffer is empty, the device driver again reads a scancode from the read buffer, calls the 
translation function with it, and subsequently reads the translated characters out of the translated 
buffer. 


If the translation function determines that it cannot convert the scancode into a meaningful character 
by itself (for example, the scancode is the beginning of a multiple-code sequence such as OxE0, Ox6B 
for an arrow key), it may request further scancodes by using the ringBufGet() function on the read ring 
buffer (rcv_ring). The translation function should read one complete sequence of scancodes and then 
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return, whether or not it has been able to convert those scancodes into a translated character. It 
should not block waiting for further key presses. 


The file <sys/keyb.h> includes many useful constants, for example scan code values for special keys. 
The samples directory also contains the source code for the keyboard device driver, including the 
translation function and the translation table that it uses. 


9.3.3. I2C Device Driver 


The I2C driver supports reading and writing to devices attached to the I?C bus. The nature of the IC 
bus means that support is implemented as |@C-specific functions, and not through the OS Open 
device driver model used for other device drivers. 


9.3.3.1. Functional Description 


¢ Allows master reads and writes 
¢ Only supports 7 bit addresses 
¢ Only supports slow (100kHz) bus 


9.3.3.2 12C Initialisation 


The I2C device is initialised by a call to i2c_setupdriver(), passing in the base address for the 
memory-mapped I2C registers. 


#include <sys/i2cLib.h> 
#include <ppcLib.h> 
rce=i2c_setupdriver (IIC_BASE_ADDRESS) ; 


IIC_BASE_ADDRESS is defined by including <ppcLib.h>. 


9.3.3.3 I2C read 


Data is read from an I2C device by using the i2c_read() funtion. The caller supplies the device 
address and information about the read. This includes an optional subaddress which is required by 
some devices. A flags parameter is used to specify whether the subaddress is present or not. Also 
supplied are a pointer to a place to store the data and a count of how many bytes to read. Between 1 
and 4 bytes may be read on each call. 


If a subaddress is specified, the device driver first writes the subaddress to the target device, waits for 
the write to complete, then issues the read. 


If the read completes successfully the function returns 0, otherwise it returns -1 if an error occurs, 
such as no response from the device within a timeout period. 


Other flags which may be passed in include the ability to specify the values of the Chaining and 
Repeated Start bits in the I2C Control register. Constants for the flags values are in <sys/i2cLib.h>. 


#include <sys/i2cLib.h> 

int rc; 

unsigned char device, subaddress; 
unsigned char data[4]; 


/* Read 4 characters from the device, using the given subaddress */ 
rc=i2c_read(device, subaddress, 4, data, I2C_FLAGS_SUBADDR) ; 


Revised 8/22/00 v. 0.8 Application Libraries and Tools 9-15 


—Preliminary Copy 


9.3.3.4 12C write 


Data is written to an I2C device with the i2c_write() function. The caller passes the device address 
and the data to be written, along with other information. This includes an optional device subaddress. 
The flags parameter specifies whether the subaddress is present. Also passed is the data to be 
written and the length of the data. A total of 4 bytes can be written on an I2C write, and this number 
includes the subaddress. So if no subaddress is specified, bewteen 1 and 4 bytes of data may be 
written. However, if a subaddress is specified, between 0 and 3 bytes of data are allowed. It is 
possible to only write the subaddress, with no accompanying data, which is why a data length of 0 is 
allowed only when a subaddress is specified. 


As on aread, the flags parameter may specify the value of the Chaining and Repeated Start bits to be 
used in the I2C Control register. 


#include <sys/i2cLib.h> 

int rc; 

unsigned char device, subaddress, device2; 
unsigned char data[4]; 


/* Write 3 characters to the device, using the given subaddress */ 
rc=i2c_write(device, subaddress, 3, data, I2C_FLAGS_SUBADDR) ; 


/* Write 4 characters to another device, without a subaddress */ 
rc=i2c_write(device2, 0, 4, data, 0); 


9.3.3.5 Accessing I2C Registers 


Functions are provided for directly reading and writing the I2C registers. The I2C registers values are 
specified in <sys/i2cLib.h>. 


To read a register, use i2c_read_reg(), passing in the register name and pointer to a place to store the 
value. 


#include <sys/i2cLib.h> 
unsigned char reg_val; 
i2c_read_reg(I2C_STATUS, &regval) ; 


To write a value to a register, use i2c_write_reg(), passing in the name of the register and the data to 
be written to it. 


#include <sys/i2cLib.h> 
i2c_write_reg(I2C_LO_SLAVE_ADDR, 0x42) ; 


9.3.4 VGA Support 
OS Open provides VGA display support for a PCI VGA display adapter. 


A subset of VGA modes is supported. There are also a set of functions to perform basic interactions 
with the VGA, in both text and graphics modes. The VGA may be used purely as a library, or it may 
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also be installed as a device driver, in which case it may be attached as an output-only device, and 
output streams such as stdout and stderr may be directed to it. 


9.3.4.1 VGA Card Initialisation 


The VGA card can be initialised by a call to vga_init(). This will detect whether a VGA card is present 
in a PCI slot, and initialise it. Currently only one VGA card is supported in OS Open. Once the card 
has been initialised, it can be set to one of the supported modes listed in sys/vgaLib.h, by using the 
vga_set_mode() call. 


9.3.4.2 Common Functions 


Several functions are supported in both text and graphics mode. These either perform functions which 
are common to both modes, or which are independant of the current mode. 


vga_set_mode() places the VGA adapter in the specified mode. It does not clear the screen, and in 
text modes the cursor is turned on and positioned at the top left of the screen. Text mode is selected 
by passing in the parameter VGA_MODE_TEXT_80x25. 16 color graphics are available with 
VGA_MODE_GRAPHICS_640x480x16 and 256 colors with 
VGA_MODE_GRAPHICS_320x200x256. 


The screen dimensions of the current mode can be obtained with the function 
vga_get_screen_dimensions(). This provides the x,y dimensions of the screen, and the number of 
colors available. Note that the screen coordinates start at O and therefore end at 1 less than the value 
returned by this function. For example, in 640x480 mode, the function will return values of 640 and 
480, and the pixels are numbered 0-639 and 0-479. In text mode, the values returned are the number 
of character positions (80 by 25), not the number of pixels. 


The address of the memory-mapped screen can be obtained with vga_get_vid_mem_start(). This 
can be useful if you want to write code which directly address the video memory without going 
through the functions available in vgaLib. 


The screen can be cleared by the function vga_cls(). In text modes this fills the screen with spaces, 
with the default attribute of a black background. The cursor is positioned at the top left corner of the 
screen (location 0,0). In graphics modes, the value 0 is written to all pixels. 


9.3.4.3 Text mode 


The text mode supported is VGA mode 2". This is a 16-color mode, 80 columns by 25 rows. The 
mode is selected by calling vga_set_mode(VGA_MODE_TEXT_80x25). This should usually be 
followed by a call to vga_cls() to clear the screen. 


Cursor and scrolling 


By default, the cursor is turned on, and placed in the top left corner of the screen. If you wish to 
disable the cursor, you must first read the cursor attributes using vga_get_cursor_info(), set the 
cursor state to off and then write back the cursor attributes using vga_set_cursor_info(). 


#include <sys/vgaLib.h> 
struct cursor_info_t cursor; 
vga_get_cursor_info(&cursor); 


cursor.state=VGA_CURSOR_OFF; 
vga_set_cursor_info(&cursor) ; 
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Similarly, the cursor type can be changed to a block by setting cursor.state to 
VGA_CURSOR_BLOCK, or back to the default underline by setting cursor.state to 
VGA_CURSOR_UNDERLINE. 


The cursor can be positioned anywhere on the screen by setting the x and y coordinates: 


struct cursor_info_t cursor; 

vga_get_cursor_info(&cursor) ; 

cursor.x=0; /* put the cursor at the start of the current line */ 
vga_set_cursor_info(&cursor) ; 


Scrolling the screen up can be done with vga_scroll_up(). If you are writing an application, such as a 
terminal emulator, which needs to scroll the screen, you should check whether the data being written 
will run off the bottom of the screen, and call vga_scoll_up() to scroll the screen. 


An example of how to print a string of characters while checking for scrolling is included in the sample 
VGA device driver source code: 


/* print length characters from buffer buff[], with scrolling */ 
int i, colors; 

struct vga_pos dim; 

struct vga_cursor_info_t cursor; 


vga_get_screen_dimensions(&dim, &colors); 
for (i=0;i<length;i++) { 
vga_get_cursor_info(&cursor); 
vga_print_char_at_cursor (buff [i],VGA_ATTR_DEFAULT) ; 
/* check if cursor was at end of screen */ 
if ((cursor.y == dim.y-1) && /* on last line of screen */ 
(cursor.x == dum.x-1)) { /* and at last column */ 
vga_scroll_up(); 
} 
} 


Character Attributes 


In the color text mode every character printed has an attribute associated with it. This consists of a 
foreground color (the color of the character itself), a background color, an option to make the 
character blink, and an option to intensify the foreground color. The intensified forground colors are 
effectively 8 extra colors (intensified black appears grey, etc). 


The attribute values are listed in the header file <sys/vgaLib.h>. They can be logically OR’d together 
and used on calls such as print_char_at_cursor‘(). 


/* Print an intense red character on a blue background and make it blink */ 
print_char_at_cursor(*X’,VGA_FG_RED | VGA_INTENSE | 
VGA_BG_BLUE | VGA_BLINK); 


A default value is defined, VGA_ATTR_DEFAULT, which is a non-intensified white foreground with a 
black background. 
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9.3.4.4 Graphics Modes 


The graphics modes supported have functions which perform common functions and insulates the 
programmer from the differences in the VGA hardware between the different VGA modes. The 
640*480 mode, with 16 colors, is VGA mode 12h. The 320*200 mode, with 256 colors, is VGA mode 
13h. 


The most basic operation is to set a pixel to a specified color. This is done with vga_set_pixel(). The 
parameters are the x and y coordinates and the value to be written to the pixel. 


The VGA architecture allows significant performance improvements if multiple adjacent pixels are 
written at the same time, and even more improvement if all the pixels have the same color. The 
function vga_fill_block() will fill a rectangular block with pixels of all the same color. Note that by 
specifying a height parameter of 1, a horizontal line can be drawn, and similarly a width value of 1 
draws a vertical line. The performance improvement over separate calls to vga_set_pixel() is quite 
noticeable, particularly in 16 color mode. The sample program supplied with OS Open draws color 
bars on the screen - this can take several seconds with the individual set_pixel calls, but appears 
instantaneous when using the block fill. 


To write a line of data, the function vga_write_data() can be used. This takes a line of data and writes 
it to the display, starting at the given x,y coordinates. If the data extends past the end of the line it will 
wrap to the start of the following line. This means that an entire screen of data can be written with one 
call. For 256-color mode, the data is clearly 8 bits, and so is byte-aligned. For 16-color mode, 
however, the data is only 4 bits for each pixel. This can be passed byte-aligned (with the top 4 bits of 
each byte being ignored), or it may be nibble-aligned, with each byte holding data for 2 pixels. The 
parameter packed is used to distinguish between these two modes, and can take the values 
VGA_DATA_PACKED or VGA_DATA_NOT_PACKED. An example of where packed data may 
originate is in a graphics file, such as one in TIFF format. Data can be read one line at a time froma 
TIFF file, then either truncated or padded to fit the screen width, and written directly with the 
vga_write_data() call. 


9.3.4.5 VGA registers 


It is a tradition with programming VGA devices that sooner or later the programmer will want to access 
the VGA registers directly. Sometimes that’s because the provided function calls are too general, and 
therefore too slow, or because the function needed is not provided by library or BIOS functions. 
Values for VGA registers are provided in the vgaLib.h header file. The inbyte() and outbyte() functions 
in ioLib can be used to access these registers. 


Sample code is provided which demonstrates the use of these calls. For example, to write to one of 
the attribute registers you may create a simple function: 


#include <ioLib.h> 
#include <sys/vgaLib.h> 


void write_attr_reg(char index, char data) { 
inbyte((unsigned char *)STATUS_1); 
outbyte((unsigned char *)ATTR_INDEX, index); 
outbyte((unsigned char *)ATTR_DATA_OUTPUT, data); 
return; 


} 


Then to write the values 0 to 15 to each attribute register in turn, you may use: 


Revised 8/22/00 v. 0.8 Application Libraries and Tools 9-19 


—Preliminary Copy 


for (i=O0;i<=15;i++) { 
write_attr_reg(i, i); 
} 


write_attr_reg(0x20,0); /* Turn on video */ 


This particular piece of code is useful when you have a new color palette which you wish to use. After 
rewriting the color registers (using outbyte()’s to the DAC_DATA register) you can update the palette 
registers to map colors 0 to 15 directly into color registers 0 to 15. See the sample file tifdemo.c which 
reads in an image from a TIFF file, writes the palette information from the file to the VGA color 
registers, then writes the image to the screen. This handles images with 16 and 256 colors, both 
packed and unpacked data. 


9.3.4.6 VGA device driver 


Instead of calling individual VGA functions directly, the VGA device may be installed as a device 
driver. This uses the VGA in text mode only. The advantage of this mode is that it allows the stdout 
and/or stderr streams (or any other output stream) to be directed to the VGA screen. The VGA device 
driver contains a simple terminal emulator which handles ASCII control characters such as carriage- 
return, line-feed and backspace. It also handles automatic scrolling of the screen. Along with the TTY 
device driver, which handles input keys including the arrow keys, tab etc, this can act as a basic ASCII 
TTY terminal. 


The device driver can be installed like this: 


#include <sys/vgaLib.h> 
#include <sys/devLib.h> 
#include <sys/devDrivr.h> 
int rc, vgadev; 


rc=dev_io_init (32,32); 
rce=driver_install(&vgadev, vgadd_init); 
rc=device_install (“/dev/vgal”, CHRTYPE, vgadev) ; 


The device can then be installed as the output device for the tty driver. First, set up a structure for 
ttyLib to refer to the VGA device: 


#include <ttyLib.h> 
#include <fcntl.h> 


commd_t vgacommd = {(int(*) ())open, {(int)”/dev/vgal”, O_WRONLY }}; 


Note that “/dev/vga1” must match the string used in the device_install(). Now install the tty device. The 
following code assumes that an input device has already been initialised, and the structure commd 
points to that input device, and that defaultAttr is an initialised attribute structure. An example of this is 
provided in the sample file io_init.c, which initialises the serial port. 


int ttydev; 


rce=driver_install (&ttydev, tty_init); 
rc=device_install(“/dev/tty0”, DTYPE_TTY, ttydev, &commd, &vgacommd, 
&defaultAttr); 
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/* Now open stdin, stdout, stderr */ 

fdl=open (“/dev/tty0”,O_RDONLY) ; 

fd2=open (“/dev/tty0”,O_WRONLY) ; 

fd3=open (“/dev/tty0”,O_WRONLY) ; 

re=fs_init(); /* Initialise file system - now we’re ready to go */ 


printf(“hello world\n”); /* output appears on the VGA screen */ 
At this point all OS Open stdout and stderr output, for example from OpenShell, will appear on the 
VGA screen. 


9.3.4.7. VGA sample 


A sample VGA program is included in the OS Open samples directory. This consists of the files 
vgasamp.c and tifdemo.c. These files can be compiled and linked in to the standard applprog image. 


The sample code requires access to some graphics files which are included in the samples/ramdisk 
directory. These may be loaded into a RAM disk which is linked into the applprog image. From the 
samples directory, issue the command “rambuild -e ramdisk”. This creates a file ramdata.s containing 
the data from the files in the ramdata subdirectory. Edit the makefile and ensure that ramdata.s is 
being included in the build of applprog - typically this is done by adding ramdata.s to the same 
variable as asmsamp.s, which is included by default: 


SAMP_S = asmsamp.s ramdata.s 
Edit thread0.c to ensure the ramdisk is being included and preloaded: 
Ensure #define TO_RAMDISK is uncommented. 
In function do_ramdisk, ensure there is a declaration: 

extern char _ram_image_data[]; 


and that the device_install() call references _ram_image_data and provides a sufficiently large RAM 
disk (1024000 bytes in this example): 


rc=device_install(“/ram”,BLKTYPE, devhandle, 1024000, _ram_image_data) ; 


Save the thread0.c file you have been editing. Make sure your VGA card is inserted into a PCI slot on 
the board, and it is connected to a monitor which is powered on. Build the applprog image by using 
the command “make”. If there are any unresolved cross-references, make sure that the libraries 
vgaLib.a and pciLib.a are being linked in. Also ensure the flag -Ball_archive is being used when 
linking, to ensure code does not get garbage-collected out of the image. Then download the image to 
the evaluation board. See the OS Open User’s Guide for more information on building and 
downloading samples. 


When the applprog image loads and runs on the board, it will display the OpenShell prompt “OS 
Opens”. At this prompt, enter the command vga_test(). You should see the VGA demonstration 
program running on the VGA monitor. 


9.3.5 Ethernet Device Driver 


The Ethernet device driver is a character device driver supporting packet level read/writes to the 
Ethernet controller. The driver features the ability to open multiple files. Each file receives packets for 
a specific standard Ethernet or 802.3 address. 
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Function highlights are: 


¢ Up to eight receive channels 
¢ Size of receive buffer pool determined by user at driver install time. 


Refer to the OS Open sample file thread0.c for an example of installing the ethernet device driver and 
to samples/enetLib for the driver source code. 


9.3.5.1. Device Driver Installation 


The Ethernet device driver is installed by calling the driver_install() function. Following is an example 
of Ethernet device driver installation: 


rc=driver_install (&devhandle_enet, 


enet_init, /* device driver init routine */ 
ENET RECEIVE _BUFFERS, /* num_blocks;# of recv buffers*/ 
NULL, /* enet_descriptor pointer */ 
NULL, /* enet_buffer pointer */ 


board_config_ptr->mac_address); /* mac_array */ 


num_blocks is the number of receive buffers used by the device driver. This value must be a multiple 
of 4. 


enet_descriptor points to a physically contiguous portion of memory the device driver uses for receive 
and transmit buffer descriptors. The portion of memory must be at least (8 * num_blocks) + 32 bytes 
in size, and 32 byte aligned. If enet_descriptor is NULL, the device driver will attempt to allocate the 

needed space based on the value of num_blocks 


enet_buffer points to a physically contiguous portion of memory the device driver uses for receive and 
transmit buffers. The portion of memory must be at least 296 * num_blocks + 1568 bytes, and 32 byte 
aligned. If enet_buffer is NULL, the device driver will attempt to allocate the needed space based on 
the value of num_blocks. 


Note: The device driver can not allocate memory that is guaranteed to be physically contiguous in 
OS Open with Virtual Memory, so in this case enet_buffer must point to the buffer to be used. 


mac_array points to the 6 byte ethernet hardware address. Typically this value is obtained from the 
ROM Monitor's get_board_cfg() function. 


Upon successful installation, driver_install() returns 0; otherwise -1 is returned. For more information 
about the driver_install() function, refer to the OS Open Programmer's Reference and the OS Open 
samples thread0.c file. 


9.3.5.2 Device Installation 


After the Ethernet device driver is installed, Ethernet devices can be installed using the 
device_install() function. Following is an example of device installation. 


rc=device_install("/dev/en0", CHRTYPE, devhandle); 


For device installation, devhandle is the value obtained from the driver_install(). Device type 
CHRTYPE is defined in <sys/devDrivr.h>. 


9-22 PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


— Preliminary Copy 


Upon successful installation, device_install() returns 0; otherwise -1 is returned. At this point, files 
may be opened against the Ethernet device. 


9.3.5.3 Opening and Closing Ethernet Files 


After the device is installed, the open() system call can be used to open a particular device. Following 
is an example of the open() system call used to open an Ethernet port. 


fdl=open ("/dev/en0", O_RDWR) ; 


When successful, open() returns the open file descriptor; otherwise -1 is returned. open() can be 
called multiple times against the same Ethernet device. 


When using the close() function, the call to the driver-specific close() is deferred until all open files on 
the device are closed. This means that when an Ethernet file is closed, the channel address 
associated with the file will not be freed if another Ethernet file is open. Be aware that if the Ethernet 
interface has been connected to the TCP/IP protocol stacks via enet_attach(), there will always be a 
file open against the Ethernet device, and therefore no channel addresses will be freed even if all the 
files the application opened are closed. To insure that the channel address will be freed, the 
ENET_CLEAR_CHANNEL ioctl() should always be called for an Ethernet file before closing it. 


For more information about the open() and close() functions, refer to the OS Open Programmer's 
Reference. 


9.3.5.4 Reading and Writing 


After successfully installing and opening the Ethernet port, the write() function can be issued. The 
write buffer must contain a complete Ethernet packet. The universally administered address that was 
found in the ISA card read only storage (ROS) passed to driver_install() will be copied into the 
source address field by the device driver. There are prototype Ethernet header structures for both 
standard Ethernet and 802.3 Ethernet packets in <enet.h>. Note that packets must be between 60 
and 1514 byte in length (inclusive). 


Before reading from the Ethernet file, an additional step must be performed. The Ethernet device 
driver supports up to 8 receive channels. What this means is that up to 8 files can be open for read or 
read/write simultaneously, and files will receive only those packets that have been selected for them. 
Packet selection is by packet type, in the case of standard Ethernet, and by destination SAP in the 
case of 802.3 Ethernet. The selection address is set with the ioct]| ENET SET CHANNEL command, 
discussed below. 


fd7 is the value obtained from the open() call. 


fdl = open(“/eno”,O_RDWR) ; 
ioctl (fd, ENET_SET_CHANNEL, 5,2); 
/* send packet from buffer */ 
write (fd,buffer, count); 
/* get received packet into buffer */ 
read(fd,buffer, count); 
close (fd); 


For more information on read() and write() functions, refer to the OS Open Programmer's Reference. 
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9.3.5.5 I/O Control 


The ioctl() call issued against the Ethernet device driver accepts the following commands. In each of 
these commands, fd is the value obtained from the open() call. 


9.3.5.6 ENET_SET_ CHANNEL 


This command sets the receive channel address of the file. Once set, a receive channel address 
cannot be used in a subsequent ioctl ENET_SET CHANNEL command unless it is first cleared with 
the ioctl ENET_CLEAR_CHANNEL command. 


re = ioctl(fd, ENET_SET_CHANNEL, 
packet_type,/* packet type is an unsigned integer containing 
the channel address */ 
type_length);/* specifies how many of the least sig bytes of 
the packet type are to be used.Only values 1 and 
2 are valid. */ 


A word about packet addresses. For standard Ethernet, the packet type is a 2-byte field right after the 
hardware source address. If tyoe_length is 2, the packet_type parameter is assumed to refer to a 
standard Ethernet packet type. For a type_length of 1, the packet_type is assumed to contain a 1-byte 
destination SAP. 


The incoming packets are differentiated as follows: For 802.3, there is a length field immediately after 
the source address. By convention, Ethernet packets are 1500 bytes or less, and valid Ethernet types 
are > 0x600. Hence, if the field after the source address is less than 0x600, the packet is assumed to 
be an 802.3 packet, and the 1 byte packet_type is compared against the destination SAP. Some 
reserved type values should not be generally used. They are defined in the file <netinet/if_ether.h>. 


9.3.5.7 ENET_CLEAR_CHANNEL 


This command clears the receive channel address of the file. This enables the device driver to free up 
internal resources and return any unread packets on this channel to the receive buffer pool. Once the 
receive channel address is cleared, it can be used again with the ioctl ENET_SET_CHANNEL 
command. The file can then be set to another receive channel as well. 


re = ioctl(fd, ENET_CLEAR_CHANNEL) ; 


9.3.5.8 ENET_QUERY_ADDRESS 


This ioctl command retrieves the universally administered address that was assigned during 
device_install. 


unsigned char ua_address[6]; 
re = ioctl(fd, ENET_QUERY_ADDRESS, ua_address) ; 


The address is copied into the area supplied as the first data parameter to this ioctl. 


9.3.6 ROM Monitor Ethernet Device Driver 


The OS Open ROM Monitor Ethernet device driver provides network access to the applications 
running on the board while still allowing the ROM Monitor to access the RISCWatch debugger over 
the ethernet. 
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This device driver uses code resident in the ROM monitor to send and receive ethernet packets. A 
different IP address must be specified to distinguish the packets from ROM Monitor and OS Open. I/O 
initialization should be done by calling dbg_ioLib_init() rather than ioLib_init(). 


The ROM Monitor Ethernet device driver is installed by calling biosenet_attach(). Following is a 
prototype of this function. 


#include <benetLib.h> 
int biosenet_attach(unsigned long ipaddr, int init_flag); 


Upon successful installation, biosenet_attach() returns 0; otherwise -1 is returned. The IP address 
for OS Open is specified in the joaddr parameter. The init_flag specifies whether the Ethernet 
controller needs to be initialized. If init_flag is set to 0 then the Ethernet controller is not initialized. If 
init_flag is set to a non-0 value, initialization of the Ethernet controller is performed. Please see 
samples/thread0.c for example code. 


9.4 Environment Startup and Initialization 


The following section describes the processing that occurs when the evaluation board environment is 
initialized. 

Upon power-up or reset the ROM Monitor initializes the processor and other peripherals on the board. 
If a ROM Monitor load is attempted (via option 0), all enabled power-on tests are executed and, 
following their completion, a bootp request is sent to the host. This request involves an exchange of 
UDP packets corresponding to the bootp protocol. In essence, the ROM Monitor asks for and is 
supplied with the name of the boot image file on the host workstation. tftp (Trivial File Transfer 
Protocol) is then initiated by the ROM Monitor to transfer the boot image to the evaluation board. 


Once the file has been transferred, two simple checks are made. A “magic number” in the boot 
image’s 32-byte header verifies that the image is one that can be loaded by the ROM Monitor (i.e., a 
file created by the eimgbld tool - see appendix B for details of the load format). The ROM Monitor also 
checks that the supplied boot image’s start address does not overlay sections of reserved DRAM. 
After the load is complete, control is transferred to the specified entry point in the boot image, which is 
in the bootstrap program. 


When using RISCWatch’s load image command to load a boot image file, the debugger strips off the 
file’s 32-byte header and loads the remaining bytes of the file onto the board. The start address of the 
load is designated in bytes 4-8 of the header. Once loaded, the IAR register is set to the boot image’s 
entry point as defined in bytes 16-19 of the header. This entry point is in the bootstrap code. See the 
“Running Your Programs” section in the RISC Watch Debugger User's Guide for additional information 
on loading files. 


9.4.1. Board Bootstrap 


The source for OS Open’s bootstrap code is included in the samples\bootLib directory. The 
bootstrap program performs the following functions: 


1. Unpacks the boot image format, placing the .text and .data sections in the addresses specified at link time. 
2. Modifies the kernel configuration block with new heap size and start address. 


3. Sets the .bss section to zeros, in accordance with ANSI C requirements. 
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9.4.2 Environment Initialization 


OS Open requires information about the system environment at initialization. The following source 
files, which are included with the samples, are used to supply that information and to establish the 
working environment. 


basic_os.c Contains pieces of config.c, io_init.c, panic.c, threadO.c, and utils.c to 
provide a minimal OS Open configuration 

config.c Configures the OS Open kernel 

io_init.c Initializes OS Open’s I/O subsystem 

network.c Configures the host names and addresses for your environment 

panic.c Provides a sample panic function 

thread0.c Configures various features of OS Open (networking, remote debugger, 
etc.) 

utils.c Provides some useful utilities such as dir() to produce a directory listing 


Additional information can be found in the “Configuring the OS Open Operating System” and 
“Developing OS Open Applications” chapters in the [BM OS Open User's Guide. 


9.5 Tools 


Several host based tools are provided to assist you in creating your own applications for the board. 
The tools can also be used for ROM program development. 
9.5.1 elf2rom 


elf2rom takes an ELF format executable file (output from the linker/binder), extracts the text and data 
sections, and writes them to a binary file. The resulting binary file can be programmed into ROM 
using a ROM programmer or the flash update utility included with board support software. 


Syntax: 


elf2rom [-v] [-d] [-p] [-s size] [-i offset] [-o output_file] input_elf 
Description: 


The program takes the input file input_elf, assumed to be an ELF file output from the linker, extracts 
the text and data sections, and writes them to the file, output_file. There are several optional flags that 
can affect elf2rom processing. They are described below. 


“Vv The verbose flag causes information about the generated output file to 
be written to stderr at the completion of the utility. This information 
includes the sizes and origins of the various sections and entry point. 


-d The debug flag will cause the symbol information from the input ELF file 
to be included after the data section in the output binary file. 
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-p 


-i offset 


long block_id 
long entry_point 
long toc_ptr 


long text_size 


long text_p_addr 
long data_size 
long data_p_addr 
long bss_size 
long bss_p_ addr 
long num_syms 


long sym_p_addr 


long text_offset 


-o output_file 


input_elf 


Revised 8/22/00 


v. 0.8 


The promotion flag causes the data section to be aligned on a full word 
boundary if possible. This alignment facilitates full word moves of data to 
the appropriate target address without causing alignment exceptions. 


The size flag causes the output binary file to be padded to a particular 
size. This option is useful if it is necessary to create binary files that are 
the same size as a target ROM device. Error messages are generated if 
the generated image exceeds the specified size. 


The info flag places an information block into the output binary file at the 
specified offset. Since this info block overlays what is currently in the file 
at the specified offset, space should be reserved for its placement. The 

info block contains the following fields. 


Magic Number 0xBFAB0030 
Entry point of image 
Used for XCOFF; not used for ELF 


Size of text section in bytes also offset from beginning of image to data 
section 


Text origin address as generated in ELF module 

Size of data section 

Data origin as specified in generated ELF module 

Size of bss section 

bss origin as specified in generated ELF module 

Number of symbols from symbol section only valid if debug flag is set) 


Address of symbol table. Calculated as text origin + offset of symbols 
with created ROM image 


Offset of text section from beginning of original ELF file. This information 
is required by certain debuggers 


Allows the specification of an output file name. The default name is 
input_elf.img. 


This is simply the ELF binary input file. (elf2rom only) 
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Figure 9-1 shows the relationship of the various sections in the produced output file. The figure 
assumes that the info block flag [-i] was specified with an offset of 0x00. 


Padding to bring she of 
image to size NS 
(if size specified) 


Symbol Section 


(if debug flag specified) 
Data Size Data Section 
Text section 
Text Size 
Info Block 
Y (overlays part of text) eet of 


Figure 9-1. elf2rom Output File 


Users can find an example of using elf2rom in the ROM Monitor’s Makefile under 
osopen/m405_evb/openbios. 


9.5.2 hbranch 


hbranch places a branch at the end of a ROM image. hbranch can also be used to store a 
communication device’s network address in the ROM’s Vital Product Data (VPD) area. 


Syntax: 
hbranch [-v] [-s size] [-n net_addr] input_image 
Description: 


The program takes the input file inout_image (which must be the output of elf2rom or eimgblid with an 
information block at 0x0 relative) pads it to size size and writes a relative branch to the entry point 
recorded in the end of the image. The entry point must be a label, not a function descriptor. There are 
several optional flags that can affect hbranch processing. They are described below. 


-V The verbose flag causes information about the generated output image to be 
written to stderr at the completion of the utility. This information includes entry 
point information. 


-s size The size flag causes the image to be padded to a particular size. This facility is 
useful if it is necessary to create binary images that are the same size as a 
target ROM device. 


-n net_addr The network address flag stores net_addr, a 12 hex character network address 
(the media access control (MAC) address), in the VPD area in ROM. The ROM 
Monitor uses this option to store the EVB’s ethernet controller’s network 
address in its VPD. 
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-p patch_file The patch file flag causes the file patch_file to be placed into the image just 
before the final branch and logically inserted into the instruction stream 
between the branch at the end of the file and the entry point. The patch file is 
inserted into the image “as is” and will usually contain the binary representation 
of position independent executable instructions. See Figure 9-2 for the details 
as to how normal hbranch processing is changed by a patch file. 


input_image This is simply the source image file. The output is written to stdout. 


End of 
File 


Branch to start 
of patch file 


Branch to 
entry point 


Patch file consisting of executable instructions 


Figure 9-2. Detail of Patch File Placement 


Figure 9-3 shows the relationship of the various sections in the produced output image. 


End of 
File 


branch to ep 


VPD (at end - 512) 


Padding to bring 
image to size 
(if size is specified) 


Binary image 
produced by 
elf2rom 


Entry point 


Start of File 


Figure 9-3. hbranch Output Image 
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Users can find an example of using hbranch in the ROM Monitor’s Makefile under 
osopen/m405_evb/openbios. 


9.5.3 eimgbld 


The eimgbld tool converts an output file from the linker/binder into the format used by the ROM 
Monitor to load programs from the host onto the evaluation board. The ELF file must be an otherwise 
executable file (with the text and data addresses bound at link time) and have space reserved after 
the entry point for the load information block (see “ROM Monitor Load Format” on page B-1 for more 
details). eimgbld sets the fields within the load information block so the application’s bootstrap code 
can perform relocation. 


Since the ROM loader does no relocation and simply transfers control to the application’s entry point 
after a successful download, the application’s entry point must point to suitable bootstrap code. It is 
the bootstrap code that relocates the application based on the data placed in the load information 
block by eimgbld. 


Syntax: 
eimgbld: [ -D -P -S -v -b addr -m m_file -o o_file -s s_file -x x_file] inout_elf 
Description: 


The program takes the input file inout_e/f (which must be the final ELF executable file produced from 
the build process) and converts it into the load format used by the ROM Monitor. There are several 
optional flags that can affect eimbgld processing: 


-D Set debug flag. A flag is set in the image causing the ROM Monitor debugger to 
be invoked immediately after the image is loaded. 

-P Creates output image in PReP format. PReP format is used by some PowerPC 
platforms. 

-S Suppress symbol information. Specifying this flag will prevent the symbol table 
from being included in the image. 

-V Verbose option. Directs information about the produced image to stderr. 

-b addr Set the symbol start location to address, addr. 

-m m_file Specify the ROM address map file. The format of this file is two addresses on 
each line (start address and ending address separated by a “,”). 

-0 0 _file Allows the specification of an output file name. The default name is input_elf.img. 

-s s file Restrict symbol table to names in specified file, s_ name. The format of this file is 


one symbol on each line. 


-x x_file Suppress section names listed in specified file, x_name. The format of this file is 
one section name on each line. 


Users can find an example of using eimgbld in the sample Makefile under 
osopen/m405_evb/samples. 
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Chapter 10. OS Open Function Reference 


This chapter describes the OS Open functions for the reference board. The function calls and macros 
are arranged alphabetically by name. For information about the effective use of some of these 
functions, refer to the microprocessor’s user’s manual. 


All descriptions contain the following sections: 


* Synopsis 
¢ Library 

¢ Description 
¢ Errors 

¢ Attributes 


Examples and references are provided or referenced where appropriate. 


10.1 Attributes and Threads 


Functions and macros have attributes that affect thread execution. Depending on their behavior, 
functions may or may not be “async safe,” “cancel safe,” and “interrupt handler safe.” 
10.1.1 Async Safe Functions 


An async safe function may be entered by two or more concurrently executing threads, with each 
thread getting the correct results. 


Functions that operate only on disjoint or local data objects are reentrant, and are therefore async 
safe. For example, ppcCntlzw() operates only on its arguments, making it reentrant and therefore 
async safe. 


Functions that operate on common or global data objects may use serialization techniques, such as 
mutexes and semaphores, within the functions to ensure async safe operation. enet_send_packet() 
uses the functions semwait() and sempost() to force serialization. Refer to the OS Open User's 
Guide for more information about the use of mutexes and semaphores. 


10.1.2 Cancel Safe Functions 


The cancel safe attribute is important only to threads executing in deferred cancelability mode (the 
cancel state is enabled; the cancel type is deferred). 


A thread executing in deferred cancelability mode can execute a cancel safe function without being 
canceled. If the same thread executes a non-cancel safe function, the thread may or may not be 
canceled during execution of the function. 


10.1.3 Interrupt Handler Safe Functions 


An interrupt handler safe function may be called by a first level interrupt handler (FLIH). 
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10.1.4 Callable from Application Thread Group Functions 


This attribute is only a concern when running OS Open with Virtual Memory. A function that is callable 
from an application thread group may be called from all thread groups. A function not callable from an 
application thread group will cause an exception if called from any thread group other than the kernel 
thread group. 


10.2 Functions 


Descriptions of the functions provided specifically to support the PPC405GP design kit are listed in 
alphabetical order in Table 10-1: 


Table 10-1. Functions Specific to the PPC405GP Design Kit 


Function or Macro Description Page 
async_init() Installs the asynchronous device driver 10-10 
biosenet_attach() Attaches the Ethernet to an IP address 10-11 
clock_set() Sets the OS Open POSIX clock to the value obtained from the 10-13 

battery operated real time clock 
clockchip_get() Reads the real-time clock 10-14 
clockchip_nvram_read() Reads bytes from the clock chip’s NVRAM 10-15 
clockchip_nvram_write() Writes bytes to the clock chip’s NVRAM 10-16 


clockchip_set() Sets the real-time clock to the number of seconds since 00:00:00 10-17 
January ist, 1970 UTC 


clockchip_start() Starts the real-time clock 10-18 

clockchip_stop() Stops the real-time clock 10-19 

clockLib_init() Initializes the clockLib library routines 10-20 

dbg_ioLib_init() Initializes the I/O library when using ROM Monitor debugger or 10-21 
benetLib.a 

dcache_flush() Flushes cache lines, beginning at the effective address and 10-22 


continuing for a specified number of bytes 


dcache_invalidate() Invalidates cache lines beginning at the effective address and 10-23 
continuing for a specified number of bytes 


dma_disable() Disable a DMA channel 10-24 
dma_setup() Initialise a DMA channel for a transfer 10-25 
dma_status() Return status information for a DMA channel 10-26 
enet_init() The Ethernet device driver initialization function 10-27 
ext_int_config() Configures the interrupt level specified by an event 10-28 
ext_int_disable() Disables the interrupt level specified by an event 10-29 
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Table 10-1. Functions Specific to the PPC405GP Design Kit (Continued) 


Function or Macro Description Page 
ext_int_enable() Enables the interrupt level specified by an event 10-30 
ext_int_install() Installs a first level interrupt handler (FLIH) for an event 10-31 
ext_int_query() Returns information about the FLIH 10-32 
i2c_read() Read data from an I?C device 10-33 
i2c_read_reg() Read an I2C register 10-34 
i2c_setupdriver() Initialise the I2C device driver 10-35 
i2c_write() Write data to an I2C device 10-36 
i2c_write_reg() Write to an I2C register 10-37 
inshort_swap() Reads in a byte-swapped halfword 10-38 
int_install() Installs a first level interrupt handler (FLIH) for an event. 10-39 
int_query() Returns information about the FLIH 10-40 
inword_swap() Reads in a byte-swapped word 10-41 
ioLib_init() Initializes I/O library 10-42 
keyb_init() Initialise the keyboard/mouse controller device driver 10-43 
memcpy_io() memcpy() for I/O areas 10-44 
outshort_swap() Writes out a byte-swapped halfword 10-47 
outword_swap() Write out a byte-swapped word 10-48 
pci_find_device() Finds a specified PCI device 10-49 
pci_find_device_type() Finds a specified type of PCI device 10-50 
pci_get_io_base() Returns a PCI I/O base address 10-51 
pci_get_memory_base() Returns a PCI memory base address 10-52 
pci_init() PCI initilisation 10-53 
pci_master_abort() Looks for and clears a PCI master abort condition 10-54 
pci_read_config_reg() Reads from a PCI configuration register 10-55 
pci_write_config_reg() Writes to a PCI configuration register 10-56 
ppcAbend() Executes an invalid opcode forcing a program check interrupt 10-57 
ppcAndMsr‘() ANDs a value with the contents of the MSR 10-58 
ppcCnilzw() Counts consecutive leading zeros in a value 10-59 
ppcDcbf() Copies the cache block back to main storage (if the block resides 10-60 

in cache and has been modified with respect to main storage) and 
then invalidates the cache block 
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Table 10-1. Functions Specific to the PPC405GP Design Kit (Continued) 


Function or Macro Description Page 

ppcDcbi() Invalidates a cache block, discarding any modified contents if the 10-61 
block is valid in cache 

ppcDcbsi() Copies a cache block, discarding any modified contents if the block | 10-62 
is valid in cache 

ppcDcbz() Sets a cache block to 0 10-63 

ppcDflush() Flush and invalidate the data cache 10-64 

ppcEieio() Ensures that all storage references before the call finish before any | 10-65 
storage references after the call start 

ppcHalt() Is a one instruction spin loop, effectively putting the processor in 10-66 
an enabled wait at the point of invocation 

ppclcbi() Invalidates an instruction cache block 10-67 

ppclsync() Causes the processor to discard any instructions that may have 10-68 
been prefetched 

ppcMfsdram0_bear() Returns the value of the SDRAMO_BEAR register 10-127 

ppcMfsdram0_besr0() - Returns the value of the SDRAMO_BESRO or SDRAMO_BESR1 10-128 

ppcMfsdram0_besr1() register 

ppcMfccr0() Returns the value of the CCRO register 10-69 

ppcMfcpc0_cr0() Returns the value of the CPCO_CRO register 10-70 

ppcMfcpc0_cr1() Returns the value of the CPCO_CR1 register 10-71 

ppcMfdact1() - ppcMfdac2() Returns the value of the DAC1 or DAC2 regsiter 10-72 

ppcMfdbcr0() - ppcMfdbcri() | Returns the value of the DBCRO or DBCR1 regsiter 10-73 

ppcMfdbsr() Returns the value of the DBSR register 10-74 

ppcMfdccr() Returns the value of the DCCR register 10-75 

ppcMfdewr() Returns the value of the DCWR register 10-85 

ppcMfdear() Returns the value of the DEAR register 10-86 

ppcMfdma0_cr0() - Returns the value of the DMAO_CRO through DMA0O_CR3 10-87 

ppcMfdma0_cr3() registers 

ppcMfdma0_ct0() - Returns the value of the DMAO_CTO through DMAO_CT3 registers | 10-88 

ppcMfdma0_ct3() 

ppcMfdma0_da0() - Returns the value of the DMAQ_DAO through DMAO_DAS registers | 10-89 

ppcMfdma0_da3() 

ppcMfdma0_sa0() - Returns the value of the DMAO_SAO through DMAO_SAS registers | 10-90 

ppcMfdma0_sa3() 

ppcMfdma0_sg0() - Returns the value of the DMASBO through DMASB3 registers 10-91 


ppcMfdma0_sg3() 
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Table 10-1. Functions Specific to the PPC405GP Design Kit (Continued) 


Function or Macro Description Page 
ppcMfdma0_sgc() Returns the value of the DMAO_SGC register 10-92 
ppcMfdma0_sr() Returns the value of the DMAO_SR register 10-93 
ppcMfdvc1() - ppcMfdvc2() Returns the value of the DVC1 or DVC2 register 10-94 
ppcMfsdram0_ecccfg() Returns the value of the SDRAMO_ECCCFG register 10-130 
ppcMfsdram0_eccesr‘() Returns the value of the SDRAMO_ECCESR register 10-131 
ppcMfesr() Returns the value of the ESR register 10-95 
ppcMfevpr() Returns the value of the EVPR register 10-96 
ppcMfgpr1 () Returns the value of GPR(1) 10-97 
ppcMfgpr2() Returns the value of GPR(2) 10-98 
ppcMfiact () - ppcMfiac4() Returns the value of the IAC1 through IAC4 register 10-99 
ppcMficcr() Returns the value of the ICCR register 10-100 
ppcMficdbdr() Returns the value of the ICDBDR register 10-101 
ppcMfdcp0_addr0() - Returns the value of the DCPO_ADDRO or DCPO_ADDR1 register | 10-76 
ppcMfdcp0_addr1() 
ppcMfdcp0_membear‘() Returns the value of the DCPO_MEMBEAR register 10-81 
ppcMfdcp0_cfg() Returns the value of the DCPO_CFG register 10-77 
ppcMfdcp0_esr() Returns the value of the DCPO_ESR register 10-78 
ppcMfdcp0_id() Returns the value of the DCPO_ID register 10-79 
ppcMfdcp0_itor0() - Returns the value of the DCPO_ITORO through DCPO_ITOR3 10-80 
ppcMfdcp0_itor3() register 
ppcMfdcp0_plbbear() Returns the value of the DCPO_PLBBEAR register 10-82 
ppcMfdcp0_ram() Returns the value of the a DCPO_RAM register 10-83 
ppcMfdcp0_ver() Returns the value of the DCPO_VER register 10-84 
ppcMfsdram0_bOcr() - Returns the value of the SDRAMO_BOCR through 10-126 
ppcMfsdram0_b3cr() SDRAMO_BSCR resgister 
ppcMfsdram0_cfg() Returns the value of the SDRAMO_CFG register 10-129 
ppcMfsdram0_pmit() Returns the value of the SDBRAMO_PMIT register 10-194 
ppcMfmsr() Returns the value of the MSR register 10-118 
ppcMfpid() Returns the value of the PID register 10-123 
ppcMfpit() Returns the value of the PIT register 10-124 
ppcMfpvr() Returns the value of the processor version register 10-125 

Revised 8/22/00 v. 0.8 OS Open Function Reference 10-5 


—Preliminary Copy 


Table 10-1. Functions Specific to the PPC405GP Design Kit (Continued) 


Function or Macro Description Page 
ppcMfsdram0_rtr() Returns the value of the SDRAMO_RTR register 10-132 
ppcMfsdram0_tr() Returns the value of the SDRAMO_TR register 10-133 
ppcMfsgr() Returns the value of the SGR register 10-134 
ppcMfsler() Returns the value of the SLER register 10-135 
ppcMfsprg0()- ppcMfsprg7() Returns the value of the special purpose register generals 10-136 

(SPRGO-SPRG7) 

ppcMfsrr0() Returns the value of SRRO 10-137 
ppcMfsrr1 () Returns the current value of SRR1 10-138 
ppcMfsrr2() Returns the current value of SRR2 10-139 
ppcMfsrr3() Returns the current value of SRR3 10-140 
ppcMfsu0r() Returns the value of the SUOR register 10-141 
ppcMftb() Returns the current time base data 10-142 
ppcMftcr() Returns the value of the TCR register 10-143 
ppcMftsr() Returns the value of the TSR register 10-144 
ppcMfuicO_cr() Returns the value of the UICO_CR register 10-145 
ppcMfuicO_er() Returns the value of the UICO_ER register 10-146 
ppcMfuicO_msr() Returns the value of the UlICO_MSR register 10-147 
ppcMfuicO_pr() Returns the value of the UICO_PR register 10-148 
ppcMfuicO_sr() Returns the value of the UICO_SR register 10-149 
ppcMfuicO_tr() Returns the value of the UICO_TR register 10-150 
ppcMfuicO_vr() Returns the value of the UICO_VR register 10-151 
ppcMfzpr() Returns the value of the ZPR register 10-152 
ppcMtsdram0_bear() Sets the value of the SDRAMO_BEAR register 10-203 
ppcMtsdram0_besr0() - Sets the value of the SDRAMO_BESRO or SDRAMO_BESR1 10-204 
ppcMtsdram0_besr1() register 

ppcMtccr0() Sets the value of the CCRO register 10-153 
ppcMtcpc0_cr0() Sets the value of the CPCO_CRO register 10-154 
ppcMtcpc0_cr1() Sets the value of the CPCO_CR1 register 10-155 
ppcMtdac1() - ppcMtdac2() Sets the value of the DAC1 or DAC2 regsiter 10-156 
ppcMtdbcr0() - ppcMidbcr1() | Sets the value of the DBCRO or DBCR1 regsiter 10-157 
ppcMtdbsr() Sets the value of the DBSR register 10-158 
ppcMtdccr() Sets the value of the DCCR register 10-159 
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Table 10-1. Functions Specific to the PPC405GP Design Kit (Continued) 


Function or Macro Description Page 
ppcMtdcwr() Sets the value of the DCWR register 10-165 
ppcMtdear() Sets the value of the DEAR register 10-166 
ppcMtdma0_cr0() - Sets the value of the DMAO_CRO through DMAO_CR3 registers 10-167 
ppcMtdma0_cr3() 
ppcMtdma0_ct0() - Sets the value of the DMAO_CTO through DMAO_CTS3 registers 10-168 
ppcMtdma0_ct3() 
ppcMtdma0_da0() - Sets the value of the DMAO_DAO through DMAO_DAS3 registers 10-169 
ppcMtdma0_da3() 
ppcMtdma0_sa0() - Sets the value of the DMAO_SAO through DMAO_ SAS registers 10-170 
ppcMtdma0_sa3() 
ppcMtdma0_sg0() - Sets the value of the DMASBO through DMASB3 registers 10-171 
ppcMtdma0_sg3() 
ppcMtdma0_sgc() Sets the value of the DMAO_SGC register 10-172 
ppcMtdma0_sr() Sets the value of the DMAO_SR register 10-173 
ppcMtdvc1() - ppcMtdvc2() Sets the value of the DVC1 or DVC2 register 10-174 
ppcMtsdram0_ecccfg() Sets the value of the SDRAMO_ECCCFG register 10-206 
ppcMtsdram0_eccesr‘() Sets the value of the SDRAMO_ECCESR register 10-207 
ppcMtesr() Sets the value of the ESR register 10-175 
ppcMtevpr() Sets the value of the EVPR register 10-176 
ppcMtiact () - ppcMtiac4() Sets the value of the IAC1 through IAC4 register 10-177 
ppcMticcr() Sets the value of the ICCR register 10-178 
ppcMtdcp0_addr0() - Sets the value of the DCPO_ADDRO or DCPO_ADDRA1 register 10-160 
ppcMidcp0_addr1() 
ppcMtdcp0_cfg() Sets the value of the DCPO_CFG register 10-161 
ppcMtdcp0_esr() Sets the value of the DCPO_ESR register 10-162 
ppcMtdcp0_itor0() - Sets the value of the DCPO_ITORO through DCPO_ITOR3 register | 10-163 
ppcMtdcp0_itor3() 
ppcMtdcp0_ram() Sets the value of the a DCPO_RAM register 10-164 
ppcMtsdram0_bOcr() - Sets the value of the SDRAMO_BOCR through SDRAMO_B3CR 10-202 
ppcMtsdram0_b3cr() resgister 
ppcMisdram0_cfg() Sets the value of the SDRAMO_CFG register 10-205 
ppcMtsdram0_pmit() Sets the value of the SDRAMO_PMIT register 10-194 
ppcMtmsr() Sets the MSR 10-195 
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Table 10-1. Functions Specific to the PPC405GP Design Kit (Continued) 


Function or Macro Description Page 
ppcMipid() Sets the value of the PID register 10-197 
ppcMtpit() Sets the value of the PIT register 10-201 
ppcMtsdram0_rtr() Sets the value of the SDRAMO_RTR register 10-208 
ppcMtsdram0_tr() Sets the value of the SDRAMO_TR register 10-209 
ppcMtsgr() Sets the value of the SGR register 10-210 
ppcMisler() Sets the value of the SLER register 10-211 
ppcMtsprg0() - ppcMitsprg7() | Sets the special purpose register generals (GPRGO - SPRG7) 10-212 
ppcMtsrr0() Sets the SRRO 10-213 
ppcMtsrr1 () Sets the SRR1 10-214 
ppcMtsrr2() Sets the SRR2 10-215 
ppcMtsrr3() Sets the SRR3 10-216 
ppcMtsu0r() Sets the value of the SUOR register 10-217 
ppcMittb() Sets the current time base data 10-218 
ppcMitcr() Sets the value of the TCR register 10-219 
ppcMitsr() Sets the value of the TSR register 10-220 
ppcMtuicO_cr() Sets the value of the UICO_CR register 10-221 
ppcMtuicO_er() Sets the value of the UICO_ER register 10-222 
ppcMtuicO_pr() Sets the value of the UICO_PR register 10-223 
ppcMtuicO_sr() Sets the value of the UICO_SR register 10-224 
ppcMtuicO_tr() Sets the value of the UICO_TR register 10-225 
ppcMtuicO_ver() Sets the value of the UICO_VCR register 10-226 
ppcMizpr() Sets the value of the ZPR register 10-227 
ppcOrMsr() Performs the OR of a value and the current MSR, updating the 10-228 
MSR 

ppcSync() Causes the processor to wait until all data cache lines scheduled 10-229 
to be written to main storage have actually been written 

s1dbprinttf() A version of printf() that may be used before I/O has been 10-230 
established 

s2dbprintt() A version of printf() that may be used before I/O has been 10-232 
established for serial port 2 

timebase_speed() Returns the speed of the timebase 10-233 

timertick_install() Installs and starts the timer tick handler 10-234 
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—Preliminary Copy 


Table 10-1. Functions Specific to the PPC405GP Design Kit (Continued) 


Function or Macro Description 
timertick_remove() Removes the timer tick handler 10-235 
vga_cls() VGA - clear screen 10-236 


vga_fill_block() VGA - fill a block with a single color 


vga_get_cursor_info() VGA - return cursor information 


vga_get_screen_dimenions() | VGA - return screen dimensions 
vga_get_vid_mem_start() VGA - return starting address of video memory 


vga_init() VGA - initialise 


vga_print_char() VGA - print a character at the given coordinates 


vga_print_char_at_cursor() VGA - print a character at the cursor position 
vga_print_string() VGA - print a string at the given coordinates 


vga_print_string_at_cursor() | VGA - print a string at the cursor position 


vga_scroll_up() VGA - scroll the screen up 


vga_set_cursor_info() VGA - set cursor information 


vga_set_mode() VGA - set the VGA mode 


vga_set_pixel() VGA - write out one pixel 


vga_write_data() VGA - write out the specified data to the screen 


vgadd_init() VGA device driver initialistaion 


vs1dbprintf() A version of printf() that uses polled writes (no 10-252 
interrupts), and may be used before I/O has been 

established and accepts a va_list as a parameter 

instead of a variable number of parameters 
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async_init() —Preliminary Copy 


Synopsis 


#include <sys/asyncLib.h> 
int driver_install(int *devhandle,async_init); 


Library 
asyncLib.a 
Description 


asyncLib.a is the asynchronous device driver that supports the asynchronous communication port 
on the PPC405GP design kit platform. asyncLib.a is installed by calling driver_install() with 
devhandle as the first parameter and async_init as the second parameter. 


Errors 
None 
Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe No 
Callable from Application Thread Group No 
References 


driver_install(): OS Open Programmer's Reference 


“Device Drivers Supplied with the Board Support Software” on page 9-5 
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—Preliminary Copy biosenet_attach() 


Synopsis 


#include <benetLib.h> 
int biosenet_attach( unsigned long ipaaddr , int init_flag); 


Library 
benetLib.a 


Description 


biosenet_attach() attaches the TCP/IP protocol stack to the Ethernet device. The IP address should 
be different from the IP address defined to the 403 EVB ROM Monitor. init_flag determines if 
biosenet_attach() should initialize the Ethernet interface. The Ethernet device should be initialized 
only if OS Open was loaded through an interface other than Ethernet. A non-zero value will cause 
biosenet_attach() to initialize the Ethernet and a 0 value causes biosenet_attach() not to initialize 
the Ethernet interface. biosenet_attach() returns 0 if successful and -1 if it is unsuccessful. 


Note 1: When using biosenet_attach() the I/O should be initialized by calling dog_ioLib_init() rather 
than ioLib_init(). 


Note 2: biosenet_attach() is unavailable for OS Open with Virtual Memory. 


Errors 


None 


Example 


Initialize TCP/IP and define an IP address to biosenet_attach(). 


#include<sys/tcpipLib.h> 


int rc; 

re=tcpip_init (imyhostnamei, 1 , 100); 

if (rce!=0) { 

return(-1);} 

if (net_init() ) return(-1); 

return (biosenet_attatch(0x07010104,0)); /* specify the IP addr. and the 
init flag*/ 
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biosenet_attach() 


Attributes 


Async Safe 
Cancel Safe 
Interrupt Handler Safe 


Callable from Application Thread Group 


Processors 
PowerPC 403GA Yes 
PowerPC 403GC Yes 
PowerPC 403GCX Yes 
References 


“Ethernet Device Driver” on page 9-21 
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—Preliminary Copy clock_set() 


Synopsis 


#include <clockLib.h> 
int clock_set (void) ; 


Library 
clockLib.a 
Description 


clock_set() sets the OS Open POSIX clock to the value obtained from the battery operated real-time 
clock. The clockLib must be initialized by calling clockLib_init() prior to calling this function. 


Errors 
[EIO] Real-time clock not running. 
Attributes 
Async Safe Yes/No! 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 


1. Not Async Safe in OS Open with Virtual Memory 


References 
“clockchip_set()” on page 10-17 
“clockLib_init()” on page 10-20 
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clockchip_get() —Preliminary Copy 


Synopsis 


#include <clockLib.h> 
int clockchip_get( time_t *timeval ); 


Library 
clockLib.a 
Description 


clockchip_get() reads the battery-backed real-time clock into the timeval structure supplied by the 
user. The clockLib library must be initialized by calling clockLib_init() prior to calling this function. 


Errors 
[EINVAL] Library not initialized. 
Attributes 


Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 


References 
“clockchip_set()” on page 10-17 
“clockLib_init()” on page 10-20 
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—Preliminary Copy clockchip_nvram_read () 


Synopsis 


#include <clockLib.h> 
int clockchip_nvram_read( int index, unsigned char *buffer, int length ); 


Library 
clockLib.a 
Description 


clockchip_nvram_read() reads non-volatile RAM from the clock chip. index specifies the starting 
byte of NVRAM, buffer points to the location where the bytes will be copied to and /ength specifies the 
maximum number of bytes to read. clockchip_nvram_read() returns the actual number of bytes 
read. The clockLib library must be initialized by calling clockLib_init() prior to calling this function. 


Note: index must be within the range specified during clockLib_init() 


Errors 

[EINVAL] Library not initialized or index out of range. 
Attributes 

Async Safe No 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

References 


“clockchip_nvram_write()” on page 10-16 


“clockLib_init()” on page 10-20 
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clockchip_nvram_write() —Preliminary Copy 


Synopsis 


#include <clockLib.h> 
int clockchip_nvram_write( int index, unsigned char *buffer, int length ); 


Library 
clockLib.a 
Description 


clockchip_nvram_write() writes non-volatile RAM in the clock chip. index specifies the starting byte 
of NVRAM, buffer points to the location where the bytes will be copied from and /ength specifies the 
maximum number of bytes to write. clockchip_nvram_write() returns the actual number of bytes 

written. The clockLib library must be initialized by calling clockLib_init() prior to calling this function. 


Note: index must be within the range specified during clockLib_init() 


Errors 

[EINVAL] Library not initialized or index out of range. 
Attributes 

Async Safe No 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

References 


“clockchip_nvram_read()” on page 10-15 


“clockLib_init()” on page 10-20 
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—Preliminary Copy clockchip_set() 


Synopsis 


#include <clockLib.h> 
int clockchip_set( time_t timeval ); 


Library 
clockLib.a 
Description 


clockchip_set() sets the battery-backed real-time clock to timeval, which should contain the number 
of seconds since January 1st, 1970 UTC. 


Errors 
[EIO] Real-time clock not running. 
[EINVAL] Library not initialized. 
Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“clock_set()” on page 10-13 
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clockchip_start() 


Synopsis 


#include <clockLib.h> 
int clockchip_start( void ); 


Library 
clockLib.a 


Description 


—Preliminary Copy 


clockchip_start() starts the real-time clock. The clockLib library must be initialized by calling 


clockLib_init() prior to calling this function. 


Errors 
[EINVAL] Library not initialized. 
Attributes 


Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 


References 
“clockchip_stop()” on page 10-19 
“clockLib_init()” on page 10-20 
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—Preliminary Copy clockchip_stop() 


Synopsis 


#include <clockLib.h> 
int clockchip_stop( void ); 


Library 
clockLib.a 
Description 


clockchip_stop() stops the real-time clock. The clockLib library must be initialized by calling 
clockLib_init() prior to calling this function. 


Errors 
[EINVAL] Library not initialized. 
Attributes 


Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 


References 
“clockchip_start()” on page 10-18 
“clockLib_init()” on page 10-20 
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clockLib_init() —Preliminary Copy 


Synopsis 


#include <clockLib.h> 
int clockLib_init( unsigned char *regbase, int reg_delta, int first_index, int 
last_index) ; 


Library 
clockLib.a 
Description 


clockLib_init() initializes the clockLib library routines. regbase specifies the base address of the 
clock/nvram chip, reg_delta specifies the distance (in bytes) between each addressable byte in the 
chip. first_index and last_index indicate the range of bytes in the NVRAM that can be accessed by 
clockchip_nvram_read() and clockchip_nvram_write(). The range is specified using starting and 
ending index values (inclusive). clockLib_init() returns 0 if successful. 


A constant defining the base address of the clock_nvram chip, RTC_NVRAM_BASE_ADDRESS, is 
specified by including <ppcLlb.h>. 


Note: clockLib_init() should be called once at system initialization. 


Errors 
[EINVAL] Already initialized or index out of range. 


Example 
clockLib_init(RTC_NVRAM_BASE_ADDRESS, 1 ,0 ,0x1ff7); 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
References 


“clock_set()” on page 10-13 
“clockchip_get()” on page 10-14 
“clockchip_nvram_read()” on page 10-15 
“clockchip_nvram_write()” on page 10-16 
“clockchip_set()” on page 10-17 
“clockchip_start()” on page 10-18 
“clockchip_stop()” on page 10-19 
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—Preliminary Copy dbg_ioLib_init() 


Synopsis 


#include <ioLib.h> 
int dbg_ioLib_init( void ); 


Library 
ioLib.a 
Description 


dbg_ioLib_init() initializes the I/O library. Unlike ioLib_init(), this function allows external I/O 
interrupts to be screened by the ROM monitor, enabling debug to be performed from outside of the 
OS Open environment. Only external I/O through IRQ’s other than those used by the ROM Monitor 
are available to OS Open. 


If successful, dbg_ioLib_init() returns 0. Otherwise, dbg_ioLib_init() returns —1. 


Errors 

[ENOMEM] Insufficient memory to allocate first level interrupt handler control areas. 
Attributes 

Async Safe No 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

Callable from Application Thread Group No 

References 


“ioLib_init()” on page 10-42 
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dcache_flush() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
void dcache_flush( void *address, unsigned int count ); 


Library 
ioLib.a 
Description 


dcache_flush() flushes data cache lines, beginning at the effective address and continuing for count 
bytes. 


A cache line flush forces the current contents of the cache line to main storage (if the line is valid and 
marked as modified) and then invalidates the line. 


Note: Since cache flushes occur on cache line boundaries, the operation can occur outside of the 
bounds specified by the function call. For example, if address is X'216' and count is X'12', two 
cache lines, spanning addresses from X'200' to X'23F', would be flushed. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“dcache_invalidate()” on page 10-23 
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—Preliminary Copy dcache_invalidate() 


Synopsis 


#include <ioLib.h > 
void dcache_invalidate( void *address, unsigned int count ); 


Library 
ioLib.a 
Description 


dcache_invalidate() invalidates data cache lines beginning at the effective address given by address 
and continuing for count bytes. 


Note: Since cache invalidation occurs on cache line boundaries, invalidation can occur outside of the 
bounds implied by this command. For example, if address is X'104' and count is 16, the cache 
line spanning the addresses from X'100' to X'120' would be invalidated. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“dcache_flush()” on page 10-22 


Revised 8/22/00 v. 0.8 OS Open Function Reference 10-23 


dma_disable() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
int dma_disable( unsigned int channel); 


Library 

ioLib.a 

Description 

dma_disable() disables the specified channel (0-3). 


The dma_disable() function returns 0 if successful or -1 if channel is invalid. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“dma_setup()” on page 10-25 
“dma_status()” on page 10-26 
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—Preliminary Copy dma_setu p() 


Synopsis 


#include <ioLib.h> 
int dma_setup( unsigned int channel, unsigned long dmacr, unsigned long count, 
void* dst_address, void* src_address, struct dma_sg_t *dmasb); 


Library 
ioLib.a 
Description 


dma_setup() initialises a DMA channel for the specified transfer. channel! specifies the DMA channel, 
dst_address the destination address, src_address the source address, count the length of the data 
transfer, dmacr the value to be written to the DMACRnh register. channe/ must be a value 0-3, count 
must be greater than 0 and less than or equal to 65536. Note that the PW field in the dmacr register 
may affect the transfer size, so for memory-to-memory transfers the total data sent is the size 
specified by the PW field multiplied by the count value. 


If dmasb is non-0, a scatter/gather transfer is used, and dmasb is the address of the first descriptor 
table element, which must have been initialised before calling dma_setup(). In this case the only 
other parameter that is used is channel, the others are ignored. Note that if you set an enable 
interrupt bit in a descriptor table element, you should install an interrupt handler to process the 
interrupt, using ext_interrupt_install(). 


The dma_setup() function returns 0 if successful or -1 if channel is invalid. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User’s Manual 
“dma_disable()” on page 10-24 

“dma_status()” on page 10-26 

“ext_int_install()” on page 10-31 
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dma_status() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
int dma_status( unsigned int channel, struct dma_stat * dstat); 


Library 
ioLib.a 
Description 


dma_status() returns status information from the specified channel (0-3). The structure pointed to by 
stat is filled with status information. struct dma_stat is defined in <ioLib.h>. 


The dma_status() function returns 0 if successful or -1 if channel! is invalid. 


Errors 
None 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“dma_disable()” on page 10-24 
“dma_setup()” on page 10-25 
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—Preliminary Copy enet_init() 


Synopsis 


#include <enet.h> 
int driver_install( int devhandle, enet_init, int num_blocks, 
void *enet_descriptor, void *enet_buffer, char *mac_array) ; 


Library 
enetLib.a 
Description 


enetLib.a is the Ethernet device driver supporting packet level read/writes to the 405GP Intergrated 
Ethernet controller. enetLib.a is installed by calling driver_install() with six parameters. The first 
parameter is the device handle, devhandle. The second parameter is the device driver initialization 
function, enet_init. The third parameter is the number of 256 byte buffers allocated for the Ethernet 
driver's use, num_blocks. The fourth parameter is the address of memory to use for buffer 
descriptors, enet_descriptor. The fifth parameter is the address of memory to use for buffers, 
enet_buffer. The sixth parameter is the location of the universal MAC address assigned to the 
Ethernet controller, mac_array. 


Please see “Ethernet Device Driver” on page 9-21 for additional information. 
Errors 
None 


Attributes 


Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe No 


References 
driver_install() : OS Open Programmer’s Reference 


“Ethernet Device Driver” on page 9-21 
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ext_i nt_config() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
void ext_int_config( int event , int flags); 


Library 
ioLib.a 
Description 


ext_int_config() configures the interrupt level specified by event. The items that can be configured 
are the polarity, trigger setting and whether the event is critical. These are specified by the flags 
parameter. ioLib.h defines the interrupt levels that can be configured. 


The flags parameter can take any of the following values, which may be OR’d together: 


EXTINT_NEG_ ACTIVE or EXT_INT_POS ACTIVE 
EXTINT_LEVEL or EXT_INT_EDGE_TRIG 
EXTINT_NON_CRITICAL or EXTINT_CRITICAL 


The ext_int_config() function returns 0 if successful or -1 if eventis invalid. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“ext_int_enable()” on page 10-30 
“ext_int_install()” on page 10-31 
“ext_int_query()” on page 10-32 
“ioLib_init()” on page 10-42 


10-28 PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


—Preliminary Copy ext_int_disable() 


Synopsis 


#include <ioLib.h> 
void ext_int_disable( int event ); 


Library 
ioLib.a 
Description 


ext_int_disable() disables the interrupt level specified by event. ioLib.h defines the interrupt levels 
that can be disabled. 


The ext_int_disable() function returns nothing. 


Errors 
None 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“ext_int_enable()” on page 10-30 
“ext_int_install()” on page 10-31 
“ext_int_query()” on page 10-32 
“ioLib_init()” on page 10-42 
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ext_int_enable() 


Synopsis 


#include <ioLib.h> 
void ext_int_enable( int event ); 


Library 
ioLib.a 


Description 


—Preliminary Copy 


ext_int_enable() enables the interrupt level specified by event. ioLib.h defines the interrupt levels 


that can be enabled. 
ext_int_enable() returns nothing. 
Errors 

None 


Attributes 


Async Safe 

Cancel Safe 

Interrupt Handler Safe 

Callable from Application Thread Group 


References 

“ext_int_install()” on page 10-31 
“ext_int_query()” on page 10-32 
“ioLib_init()” on page 10-42 
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—Preliminary Copy ext_int_install() 


Synopsis 


#include <flih.h> 
#include <ioLib.h> 
int ext_int_install( int event, flih_t *new_flih, flih_t *old_flih ); 


Library 
ioLib.a 
Description 


ext_int_install() installs a first level interrupt handler (FLIH) for the external interrupt event. ioLib.h 
defines the interrupt levels that can be set. 


If new_flih is NULL, the current interrupt handler is removed for the specified event. If new_flih is non- 
NULL, it points to a flih_t structure containing the following fields: 


flin_stack Pointer to the first stack location; obtained by allocating memory and 
adding the size of the stack. flin_stack must be 16 byte aligned. 

flih_function Pointer to a function invoked when event occurs. 

arg A user-defined (void *) value passed to flih_function. 


If old_flih is not NULL, the previous values of flih_function, flih_stack, and arg are stored in the 
structure pointed to by old_flih. 


Note: to install an interrupt handler for other, non-external, interrupts, see int_install(). 


If successful, ext_int_install() returns 0. Otherwise, ext_int_install() returns —1. 


Errors 

[EINVAL] event does not refer to a valid event. 
Attributes 

Async Safe No 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

Callable from Application Thread Group No 
References 


“ext_int_enable()” on page 10-30 
“ext_int_query()” on page 10-32 
“ioLib_init()” on page 10-42 
“int_install()” on page 10-39 
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ext_int_q uery() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
#include <flih.h> 
int ext_int_query( int event, flih_t *flih ); 


Library 

ioLib.a 

Description 

ext_int_query() returns information about the first level interrupt handler (FLIH), if any, for event. 
ioLib.h defines the events for which FLIHs can query. 


The flih argument points to a flih_t structure containing the following fields: 


flin_stack Pointer to the first stack location; obtained by allocating memory and 
adding the size of the stack. 

flin_function Pointer to a function invoked when event occurs. 

arg A user-defined (void *) value passed to flih_function. If no FLIH is 


installed for the specified level, each field in the flih_t structure is 
assigned NULL. 


If successful, ext_int_query() returns 0. Otherwise, ext_int_query() returns —1. 


Errors 
[EINVAL] event does not refer to a valid event. 
Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“ext_int_enable()” on page 10-30 
“ext_int_install()” on page 10-31 


“ioLib_init()” on page 10-42 
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—Preliminary Copy i2c_read() 


Synopsis 


#include <sys/i2cLib.h> 
int i2c_read(unsigned char dev_addr, unsigned char dev_subaddr, unsigned char 
count, unsigned char *data, unsigned char flags) 


Library 
i2cLib.a 
Description 


i2c_read() reads count (1 to 4) characters from the i2c device specified by dev_addr, and places 
them in the buffer pointed to by data. The optional subaddress specified by dev_subadar may also be 
used by the device to determine which data to send. 


flags may contain any of the following viaues, OR’d together: 


I2C_FLAGS_ SUB ADDR: a device subaddress is to be used, and is in dev_subaddr 
I2C_FLAGS_CH: chaining - sets the Chain bit in the I2C Control register 
I2C_FLAGS_REP_ST: repeated start - sets the Repeated Start bit in the I2C Control register. 


The I2C driver must have been initialised with a call to i2c_setupdriver() before this function is called. 
Returns 0 if successful and -1 otherwise. 

Errors 

None 

Example 

Read 2 bytes from the specified device, using the given subaddress. 

#include <sys/i2cLib.h> 

oe 

unsigned char dev_addr, dev_subaddr; 


unsigned char data[4]; 
rc=i2c_read (dev_addr, dev_subaddr, 2, data, I2C_FLAGS_SUB_ADDR) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe No 
Callable from Application Thread Group Yes 
References 


“i2c_setupdriver()” on page 10-35 
PPC405GP Embedded Controller User's Manual 
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i2c_read_reg() —Preliminary Copy 


Synopsis 


#include <sys/i2cLib.h> 
int i2c_read_reg(unsigned char reg, unsigned char *value) 


Library 
i2cLib.a 
Description 


i2c_read_reg() reads the contents of I2C register reg, and returns it in the character pointed to by 
value. reg must be in the range 0 to 15. Constants defining the register names are in <sys/i2cLib.h>. 


Returns 0 if successful and -1 otherwise. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe No 
Callable from Application Thread Group Yes 
References 


PPC405GP Embedded Controller User's Manual 
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—Preliminary Copy i2c_setu pd river() 


Synopsis 


#include <sys/i2cLib.h> 
int i2c_setupdriver(char * base_address) 


Library 
i2cLib.a 
Description 


i2c_setupdriver() initialises the 12C device driver. This function should be called before any other l2C 
functions are attempted. The base_address parameter contains the starting address of the memory- 
mapped IIC registers. This infomration may be obtained from processor documentation, and is also 
contained in the symbol IIC_BASE_ADDRESS, obtained by including file <ppcLib.h>. 


Returns 0 if successful and -1 otherwise. 
Errors 

ENOSPC, ENOMEM: Insufficient memory 
Example 

Initialise the l2C driver. 

#include <sys/i2cLib.h> 

#include <ppcLib.h> 

anv, Eee 

rce=i2c_setupdriver (IIC_BASE_ADDRESS) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


PPC405GP Embedded Controller User’s Manual 
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i2c_write() —Preliminary Copy 


Synopsis 


#include <sys/i2cLib.h> 
int i2c_write(unsigned char dev_addr, unsigned char dev_subaddr, unsigned char 
count, unsigned char *data, unsigned char flags) 


Library 
i2cLib.a 
Description 


i2c_write() writes count characters to the i2c device specified by dev_addr, from the buffer pointed to 
by data. The optional subaddress specified by dev_subaddr may be used by the device to determine 
where to place the data. If no device subaddress is used, the value of count may be 1 to 4. If a device 
subaddress is used, count may be 0 to 3. When count is 0, only the device subaddress is written. 


flags may contain any of the following viaues, OR’d together: 


I2C_FLAGS SUB ADDR: a device subaddress is to be used, and is in dev_subadadr 
I2C_FLAGS_CH: chaining - sets the Chain bit in the I2C Control register 
I2C_FLAGS_REP_ST: repeated start - sets the Repeated Start bit in the I2C Control register. 


The I2C driver must have been initialised with a call to i2c_setupdriver() before this function is called. 
Returns 0 if successful and -1 otherwise. 

Errors 

None 

Example 

Write 2 bytes to the specified device, using the given subaddress. 


#include <sys/i2cLib.h> 

int rc; 

unsigned char dev_addr, dev_subaddr; 

unsigned char data[4]; 

rce=i2c_write (dev_addr, dev_subaddr, 2, data, I2C_FLAGS_SUB_ADDR) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe No 
Callable from Application Thread Group Yes 
References 


“i2c_setupdriver()” on page 10-35 
PPC405GP Embedded Controller User’s Manual 


10-36 PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


—Preliminary Copy i2c_write_reg() 


Synopsis 


#include <sys/i2cLib.h> 
int i2c_write_reg(unsigned char reg, unsigned char value) 


Library 
i2cLib.a 
Description 


i2c_write_reg() writes va/ue to I2C register reg. reg must be in the range 0 to 15. Constants defining 
the register names are in <sys/i2cLib.h>. 


Returns 0 if successful and -1 otherwise. 


Errors 
None 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe No 
Callable from Application Thread Group Yes 
References 
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inshort_swap() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
unsigned short inshort_swap(unsigned short * address) 


Library 
ioLib.a 
Description 


inshort_swap() returns a halfword read from the I/O port specified by address. The halfword is byte- 
reversed, by using the Ihbrx instruction. 


After the halfword is read, the PowerPC eieio instruction is issued to enforce in-order execution of I/O. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“outshort_swap()” on page 10-47 
“inword_swap()” on page 10-41 
inshort(): OS Open Programmer's Reference 


Ihbrx instruction in PPC405GP Embedded Controller User’s Manual 
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—Preliminary Copy int_install() 


Synopsis 


#include <flih.h> 
int int_install( int event, flih_t *new_flih, flih_t *old_flih ); 


Library 
rtxLib.a 
Description 


int_install() installs a first level interrupt handler (FLIH) for event. flih.h defines the interrupt levels 
that can be set. 


If new_flih is NULL, the current interrupt handler is removed for the specified event. If new_flih is non- 
NULL, it points to a flih_t structure containing the following fields: 


flin_stack Pointer to the first stack location; obtained by allocating memory and 
adding the size of the stack. 

flih_function Pointer to a function invoked when event occurs. 

arg A user-defined (void *) value passed to flih_function. 


If old_flih is not NULL, the previous values of flih_function, flih_stack, and arg are stored in the 
structure pointed to by old_flih. 


Note: to install an interrupt handler for a device which generates an external interrupt (one handled by 
the Universal Interrupt Controller, UIC) use the function ext_int_install(). 


If successful, int_install() returns 0. Otherwise, int_install() returns —1. 


Errors 

[EINVAL] event does not refer to a valid event. 
Attributes 

Async Safe No 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

Callable from Application Thread Group No 
References 


“int_query()” on page 10-40 
“ioLib_init()” on page 10-42 


“ext_int_install()” on page 10-31 
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int_q uery() —Preliminary Copy 


Synopsis 


#include <flih.h> 
int int_query( int event, flih_t *flih ); 


Library 
rtxLib.a 


Description 
int_query() returns information about the first level interrupt handler (FLIH), if any, for event. 
flih.h defines the events for which FLIHs can query. 


The flih argument points to a flih_t structure containing the following fields: 


flin_stack Pointer to the first stack location; obtained by allocating memory and 
adding the size of the stack. 

flin_ function Pointer to a function invoked when event occurs. 

arg A user-defined (void *) value passed to flih_function. If no FLIH is 


installed for the specified level, each field in the flih_t structure is 
assigned NULL. 


If successful, int_query() returns 0. Otherwise, int_query() returns —1. 


Errors 

EINVAL] event does not refer to a valid event. 
Attributes 

Async Safe No 

Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“int_install()” on page 10-39 
“ioLib_init()” on page 10-42 
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—Preliminary Copy inwo rd_swap() 


Synopsis 


#include <ioLib.h> 
unsigned long inword_swap (unsigned long * address) 


Library 
ioLib.a 
Description 


inword_swap() returns a word read from the I/O port specified by address. The word is byte- 
reversed, by using the Ilwbrx instruction. 


After the word is read, the PowerPC eieio instruction is issued to enforce in-order execution of I/O. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“outword_swap()” on page 10-48 
“inshort_swap()” on page 10-38 
inword(): OS Open Programmer’s Reference 


Iwbrx instruction in PPC405GP Embedded Controller User’s Manual 
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ioLib_init() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
int ioLib_init( void ); 


Library 

ioLib.a 

Description 

ioLib_init() initializes the I/O library. 

If successful, ioLib_init() returns 0. Otherwise, ioLib_init() returns —1. 


ioLib_init() should not be used when using the ROM Monitor Ethernet interface or the ROM monitor 
debugger. dbg_ioLib_init() should be used instead. 


Errors 

[ENOMEM] Insufficient memory to allocate first level interrupt handler control areas. 
Attributes 

Async Safe No 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

Callable from Application Thread Group No 

References 


“dbg_ioLib_init()” on page 10-21 
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—Preliminary Copy keyb_init() 


Synopsis 


#include <sys/keyb.h> 
int driver_install(int *devhandle, keyb_init) ; 


Library 
keybLib.a 
Description 


keybLib.a is the keyboard and mouse controller device driver. keybLib.a is installed by calling 
driver_install() with devhandle as the first parameter and keyb_init as the second parameter. 


Errors 
None 
Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe No 
Callable from Application Thread Group No 
References 


driver_install(): OS Open Programmer's Reference 


“Keyboard/Mouse Controller Driver” on page 9-11 
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memcpy_io() 


Synopsis 


#include <ioLib.h> 


—Preliminary Copy 


int memcpy_io(void * target, void * source, size_t length); 


Library 
ioLib.a 


Description 


memcpy_io() is provided for compatiblity with some other paltforms whcih require special handling 
for copying which involves I/O space. In this platform memcpy_io() behaves the same as memcpy/(). 


Errors 


None 


Attributes 


Async Safe 

Cancel Safe 

Interrupt Handler Safe 

Callable from Application Thread Group 


References 


memcpy(): OS Open Programmer's Reference 


No 
Yes 
Yes 
No 
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—Preliminary Copy ocm_disable() 


Synopsis 


#include <ppcLib.h> 
int ocm_disable(int side); 


Library 

ocmLib.a 

Description 

ocm_disable() disables the specified side of the On-Chip Memory. 

Valid values for the side parameter are OCM_DATA_SIDE or OCM_INST_SIDE 


Errors 

None 
Attributes 

Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User’s Manual 
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ocm_init() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
int ocm_init (char * ocm_address,int side); 


Library 
ocmLib.a 
Description 


ocm_init() initialises the specified side of the On-Chip Memory, starting at the specified address 
ocm_address. ocm_address must lie on a 64MB boundary 


Valid values for the side parameter are OCM_DATA_SIDE or OCM_INST_SIDE 


Errors 
None 
Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User's Manual 
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—Preliminary Copy outshort_swap() 


Synopsis 


#include <ioLib.h> 
void outshort_swap(unsigned short * address, unsigned short data) 


Library 
ioLib.a 
Description 


outshort_swap() writes the halfword containing data to the I/O port specified by address. The 
halfword is byte-reversed, by using the sthbrx instruction. 


After the halfword is written, the PowerPC eieio instruction is issued to enforce in-order execution of 
1/O. 


Errors 

None 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“inshort_swap()” on page 10-38 
“outword_swap()” on page 10-48 
outshort(): OS Open Programmer's Reference 


sthbrx instruction in PPC405GP Embedded Controller User’s Manual 
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outword_swap() —Preliminary Copy 


Synopsis 


#include <ioLib.h> 
void outword_swap(unsigned long* address, unsigned long data) 


Library 
ioLib.a 
Description 


outword_swap() writes the word containing data to the I/O port specified by address. The word is 
byte-reversed, by using the stwbrx instruction. 


After the word is written, the PowerPC eieio instruction is issued to enforce in-order execution of I/O. 


Errors 
None 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“inword_swap()” on page 10-41 
“outshort_swap()” on page 10-47 
outword(): OS Open Programmer's Reference 


stwbrx instruction in PPC405GP Embedded Controller User’s Manual 
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—Preliminary Copy pci_find_device() 


Synopsis 


#include <sys/pciLib.h> 
int pci_find_device( unsigned short vendorid, unsigned short deviceid, 
unsigned int *nextp); 


Library 
pciLib.a 
Description 


pci_find_device() searches the PCI devices on the system looking for one which matches the 
vendorid and deviceid. The vendorid is compared to the Vendor ID field on each PCI device on the 
system, and the deviceid is compared to the Device ID field. 


The value pointed to by nextp determines the where the search starts. To find the first device on the 
system that matches, *nexip should be PCI_NEXT_INIT. When the search completes successfully, 
*nextp is updated with the location of the device. On a subsequent call to this function using the same 
*nextp, the search starts at the device after the last one that was found. In this way, all devices which 
match the search criteria may be found. When no device is found, *nextp is set to PCINEXT_INIT. 


If successful, returns an integer containing the bus and device numbers of the found device. For the 
format of this integer, see the description of bus_dev_func in pci_read_config_reg(). 


Errors 


Returns -1 if device is not found. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


PCI Local Bus Specification, Revision 2.1 
“oci_find_device_type()” on page 10-50 
“pci_read_config_reg()” on page 10-55 
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pci_find_device_type() —Preliminary Copy 


Synopsis 


#include <sys/pciLib.h> 
int pci_find_device_type( int class_code, unsigned int *nextp); 


Library 
pciLib.a 
Description 


pci_find_device_type() searches the PCI devices on the system looking for one which matches the 
class_code. The class code consists of 3 bytes, as defined in the PCI specification. The two most 
significant, the base class and sub-class, must exactly match the corresponding fields in the class 
code field on the PCI device. The least significant field, interface, is a bit map. In order for the device 
to completely match the class_code, it must have at least the interface bits set that are specified in the 
class_code interface map. 


In the four-byte class_code variable, the most significant byte is unused, the next byte contains the 
base class, next is the sub-class, and the least significant byte contains the interface byte. 


The value pointed to by nextp determines the where the search starts. To find the first device on the 
system that matches, *nextp should be PCI_NEXT_INIT. When the search completes successfully, 
*nexto is updated with the location of the device. On a subsequent call to this function using the same 
*nextp, the search starts at the device after the last one that was found. In this way, all devices which 
match the search criteria may be found. When no device is found, *nextp is set to PCI_NEXT_INIT. 


If successful, returns an integer containing the bus and device numbers of the found device. For the 
format of this integer, see the description of bus_dev_func in pci_read_config_reg(). 


Errors 


Returns -1 if device is not found. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


PCI Local Bus Specification, Revision 2.1 
“oci_find_device()” on page 10-49 
“oci_read_config_reg()” on page 10-55 
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—Preliminary Copy pci_get_io_base() 


Synopsis 


#include <sys/pciLib.h> 
int pci_get_io_base( int base_addr ); 


Library 
pciLib.a 
Description 


pci_get_io_base() returns the base I/O address for the PCI address specified by base_adadr. 
Typically this is used to determine where I/O space starting at address 0 appears in the CPU memory 
map. 


Errors 


Returns -1 if no base address matches base_ador. 


Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“pci_get_memory_base()” on page 10-52 
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pci_get_memory_base() —Preliminary Copy 


Synopsis 


#include <sys/pciLib.h> 
int pci_get_memory_base( int base_addr ); 


Library 
pciLib.a 
Description 


pci_get_memory_base() returns the base CPU (PLB) memory address for the PCI address 
specified by base_adar. A typical use for this is used to determine where PCI memory space starting 
at address 0 appears in the CPU memory map. 


Errors 


Returns -1 if no base address matching base_adar is mapped. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“pci_get_io_base()” on page 10-51 
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—Preliminary Copy 


Synopsis 


#include <sys/pciLib.h> 
int pci_init( void ); 


Library 
pciLib.a 
Description 


pci_init() initialises the PCI controller as a master. 


Errors 

None. 
Attributes 

Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
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pci_m aster_abort() —Preliminary Copy 


Synopsis 


#include <sys/pciLib.h> 
int pci_master_abort( void ); 


Library 
pciLib.a 
Description 


pci_master_abort() tests if a master abort happened during a previous PCI master access, and 
clears the error if so. Returns 0 if there was no master abort, returns -1 if there was. 


Errors 

None. 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
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-Preliminary Copy pci_read_config_reg() 


Synopsis 


#include <sys/pciLib.h> 
unsigned int pci_read_config_reg( int bus_dev_func, int reg, int width ); 


Library 
pciLib.a 
Description 


pci_read_config_reg() reads a register, reg, from the device specified by bus_dev_func. The amount 
of data read is specified by width, and may be 1, 2, or 4 bytes. For 2 or 4 byte reads, reg must be 
appropriately aligned. 


bus_dev_func contains the identifier for a device, consisting of the bus and device numbers. They are 
placed within the word so as to be able to be used directly by the PCI Configuration Address Register. 
The bus number is placed in bits 23:16, the device number in bits 15:11 (using PCI bit notation where 
bit 31 is most significant). 


Returns the value of the specified register. 
Errors 


Returns -1 if width is not 1, 2, or 4. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“oci_write_config_reg()” on page 10-56 
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pci_write_config_reg() —Preliminary Copy 


Synopsis 


#include <sys/pciLib.h> 
int pci_write_config_reg( int bus_dev_func, int reg, unsigned int value, int 
width ); 


Library 
pciLib.a 
Description 


pci_write_config_reg() writes value to a register, reg, in the device specified by bus_dev_func. The 
amount of data read is specified by width, and may be 1, 2, or 4 bytes. For 2 or 4 byte writes, reg must 
be appropriately aligned. For the format of bus_dev_func, see the description in 
pci_read_config_reg(). Returns 0 if successful. 


Errors 


Returns -1 if widthis not 1, 2, or 4. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“oci_read_config_reg()” on page 10-55 
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—Preliminary Copy ppcAbend() 


Synopsis 


#include <ppcLib.h> 
void ppcAbend (void) 


Library 

ppcLib.a 

Description 

ppcAbend() executes an invalid opcode forcing a Program Check interrupt. 
Errors 

None 

Example 


Force an illegal instruction exception. 


ppcAbend() 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


PPC405GP Embedded Controller User’s Manual 
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ppcAndMsr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcAndMsr (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcAndMsr() ANDs value with the contents of the MSR. 

The MSR is updated with the result of the AND operation. 
ppcAndMsr() returns the previous contents of the MSR. 

Refer to the <ppcLib.h> file for the defines of the MSR constants. 
Errors 

None 

Example 


Disable external interrupts. 


unsigned long orig_msr = ppcAndMsr (~ppcMsrEE) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“ppcOrMsr()” on page 10-228 
“ppcMimsr()” on page 10-195 
PPC405GP Embedded Controller User’s Manual 
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—Preliminary Copy ppcCnitlzw() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcCntlzw(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcCntlzw() counts consecutive leading zeros in value. 

ppcCntizw() returns the count, which ranges from 0 through 32, inclusive. 
Errors 

None 

Example 

Return count of leading zeros in variable k. 


int k; 
unsigned long k = ppcCntlzw(0x0700AA55); /* k = 5 */ 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


PPC405GP Embedded Controller User’s Manual 
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ppcDcbf() 


Synopsis 


#include <ppcLib.h> 
void ppcDcbf (void *addr) ; 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcDcbf() copies the cache block at the effective address specified by addr back to main storage (if 
the block resides in cache and has been modified with respect to main storage) and then invalidates 


the cache block. 


Effectively, this function acts like ppcDcbst() followed by ppcDcbi(). 


Errors 


None 


Example 


Flush the cache line at the effective address X'1000' to main storage and then invalidate the cache 


line. You might do this in preparation for a DMA slave transfer. 


ppcDcbf ( (void *)0x1000); 


Attributes 


Async Safe 
Cancel Safe 
Interrupt Handler Safe 


Callable from Application Thread Group 


References 

“ppcDebst()” on page 10-62 
“epcDcbi()” on page 10-61 
“ppcDcbz()” on page 10-63 
“epcDflush()” on page 10-64 
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—Preliminary Copy ppcDcbi() 


Synopsis 


#include <ppcLib.h> 
void ppcDcbi(void *addr) ; 


Library 
ppcLib.a 
Description 


ppcDcbi() invalidates the cache block containing addr, discarding any modified contents if the block is 
valid in cache. 


Errors 
None 
Example 


Invalidate the cache line beginning with 0x3000. This might be done before reading an area of 
storage updated by a DMA transfer. 


ppcDcbi( (void *)0x3000); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“epcDebf()” on page 10-60 

“epcDebst()” on page 10-62 

“ppcDcbz()” on page 10-63 

“ppcDflush()” on page 10-64 
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ppcDcbst() 


Synopsis 


#include <ppcLib.h> 
void ppcDcbst (void *addr); 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcDcbst() copies the cache block containing addr to main storage, if the block is valid in cache and 


has been modified with respect to main storage. 


Errors 


None 


Example 


Force the cache line beginning with 0x4000 to memory if the block is valid and out of sync with 
storage. This would be done to synchronize the cache and storage without invalidating the cache line. 


ppcDcbst ((void *)0x4000); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“ppcDcbf()” on page 10-60 

“epcDebi()” on page 10-61 

“ppcDcbz()” on page 10-63 

“ppcDflush()” on page 10-64 
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—Preliminary Copy ppcDcbz() 


Synopsis 


#include <ppcLib.h> 
void ppcDcbz (void *addr) ; 


Library 

ppcLib.a 

Description 

ppcDcbz() sets the cache block containing the byte referenced by adar to 0. 
The line is established, if necessary, without fetching the line from main storage. 


Note: If an invalid real address is specified, problems could occur when a subsequent attempt is 
made by the cache unit to store that line to main storage. 


Errors 


None 


Example 


Assume buffer is 16 cache lines long and cache aligned. To quickly set it to 0, set to first buffer 
address. 


char *bpt = buffer; 

for(j = 0; j < 16; jJjtt) 
{ 
ppcDcbz( (void *)bpt); 
bpt += cache_line_size; 


} 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“ppcDebf()” on page 10-60 

“epcDcbi()” on page 10-61 

“ppcDebst()” on page 10-62 

“ppcDflush()” on page 10-64 
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ppcDflush() 


Synopsis 


#include <ppcLib.h> 
void ppcDflush (void) ; 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcDflush() flushes the existing data in the data cache back into memory, invalidating all of the lines 
in the data cache, then turns off the data caches by writing Os into the Data Cache Cacheability 


Register (DCCR). 
Errors 
None 


Example 


Force data reads from memory instead of the data cache. 


ppcDflush(); 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“ppcDcbf()” on page 10-60 

“epcDebi()” on page 10-61 

“epcDebst()” on page 10-62 

“ppcDcbz()” on page 10-63 
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—Preliminary Copy ppcEieio() 


Synopsis 


#include <ppcLib.h> 
void ppcHieio (void); 


Library 
ppcLib.a 
Description 


ppcEieio() ensures that all storage references before the call finish before any storage references 
after the call start. 


The PPC405GP may internally reorder operations to storage. In the case of memory mapped I/O, 
such reordering can be undesirable and can be prevented by appropriate use of ppcEieio(). 


Errors 

None 

Example 

Ensure storage references are done in order. 


char *one_loc = (char *)0x202; 
char *two_loc = (char *)0x204; 


*one_loc OxAA; /* write a OxAA to 0x202 */ 


ppcHieio(); /* insure the store completes before setting two_loc */ 
*two_loc = 0x55; 
Attributes 

Async Safe Yes 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

Callable from Application Thread Group Yes 

References 
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ppcHalt() 


Synopsis 


#include <ppcLib.h> 
void ppcHalt (void); 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcHalt() is a one instruction spin loop, effectively putting the processor in an enabled wait at the 


point of invocation. 

Errors 

None 

Example 

Wait at the point of invocation. 
ppcHalt(); 

Attributes 


Async Safe 

Cancel Safe 

Interrupt Handler Safe 

Callable from Application Thread Group 


References 
PPC405GP Embedded Controller User’s Manual 
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Yes 
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Yes 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcIcbi(void *addr) ; 


Library 
ppcLib.a 


Description 


ppclcbi() 


ppclebi() invalidates the Instruction Cache Block pointed to by the address passed. This may be 


done after updating an instruction. 
Errors 

None 

Example 

Write a trap into location 0x3000. 
unsigned in * i_addr = (int *) 0x3000; 


*i_addr = 0x7c800008; /* tw instruction */ 
ppcDbcst ((void *) 0x3000); 
ppciIcbi((void *) 0x3000); 
ppciIsync(); 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 
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ppclsyne() 


Synopsis 


#include <ppcLib.h> 
void ppcIsync (void) ; 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppclsync() causes the processor to discard any instructions that may have been prefetched before 


ppclsync(). This call must be used after modifying instruction storage. 


Errors 

None 

Example 

Place a trap into a given address. 


*trap_address = 0x7F000008; 
ppciIsync(); 


Attributes 


Async Safe 

Cancel Safe 

Interrupt Handler Safe 

Callable from Application Thread Group 


References 
PPC405GP Embedded Controller User's Manual 
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—Preliminary Copy ppcMfccr0() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfccr0 (void) ; 


Library 

ppcLib.a 

Description 

ppcMfccr0() returns the value of the processor ccrO register (Core Configuration Register 0). 
Errors 

None 

Example 

Retrieve the value of ccr0 register. 


unsigned long current_ccr0=ppcMfccr0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfcpc0_cr0() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfcpcO_cr0 (void) ; 


Library 

ppcLib.a 

Description 

ppcMfcpc0_cr0() returns the value of the processor CPCO_CRO (chip control 0) register. 
Errors 

None 

Example 

Retrieve the value of CPCO_CRO register. 


unsigned long current_cpc0O_cr0=ppcMfcpc0O_cr0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfcpc0_cr1() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfcpcO_cril (void); 


Library 

ppcLib.a 

Description 

ppcMfcpc0_cr1() returns the value of the processor CPCO_CR1 (chip control 1) register. 
Errors 

None 

Example 

Retrieve the value of CPCO_CR1 register. 


unsigned long current_cpc0O_crl=ppcMfcpcO_cr1(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdact ()- ppcMfdac2() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdacl (void) 
unsigned long ppcMfdac2 (void) 


Library 

ppcLib.a 

Description 

ppcMfdac1() - ppcMfdac2() returns the current value of the specified register. 


The Data Address Compare registers 1 and 2 contain addresses for which debug events may be 
taken, depending on the values set in the DBCR1 register. 


Errors 

None 

Example 

Retrieve the current value of the DAC2 register. 


unsigned long dac2_value= ppcMfdac2(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMfdbcr0() - ppcMfdbcr1() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdbcr0 (void) 
unsigned long ppcMfdbcrl (void) 


Library 

ppcLib.a 

Description 

ppcMfdbcr0() - ppcMfdber1() returns the current value of the specified register. 


Dedug Control Registers 0 and 1 are used to enable debug events, reset the processor and set the 
debug mode of the processor. 


WARNING: Enabling bits 0 and 1 can cause unexpected results. Enabling bits 2 and 3 will cause a 
processor reset to occur. DBCRO and DBCR?1 are designed to be used by development tools, not 
applications. 


Refer to the file <ppc405.h> for defined constants for the DBCRO and DBCR? registers. 
Errors 

None 

Example 

Retrieve the current value of the DBCR1 register. 


unsigned long dbcri_value= ppeMfdber1(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfd bsr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdbsr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdbsr() returns the value of the processor DBSR register. 

The Debug Status Register contains the status of debug events and the most recent reset. 
The file <ppc405.h> defines constants that can be used when referring to the DBSR. 
Errors 

None 

Example 


Retrieve the value of DBSR register. 


unsigned long current_DBSR=ppcMfdbsr (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfdccr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdccr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdccr() returns the value of the processor DCCR (Data Cache Cacheability Register). 
Errors 

None 

Example 

Retrieve the value of DCCR register. 


unsigned long current_DCCR=ppcMfdccr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdcp0_addr0() . ppcMfdcp0_addrt () —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcp0_addr0 (void) 
unsigned long ppcMfdcp0_addr1 (void) 


Library 

ppcLib.a 

Description 

ppcMfdcp0O_addr0() - ppcMfdcp0O_addr1() returns the current value of the specified register. 


The Address Decode Definition Registers are part of the decompression core and are addressed 
indirectly through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the current value of the DCPO_ADDRO register. 


unsigned long dcp0_addr0_value= ppcMfdcp0_addr0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfdcp0_cfg () 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcp0_cfg (void); 


Library 

ppcLib.a 

Description 

ppcMfdcp0_cfg() returns the value of the processor DCPO_CFG compression register. 


The Decompression core Configuration Register is part of the decompression core and is addressed 
indirectly through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of DCPO_CFG register. 


unsigned long current_DCPO_CFG=ppcMfdcp0_cfg(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdcp0_esr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcpO0_esr (void); 


Library 

ppcLib.a 

Description 

ppcMfdcp0_esr() returns the value of the processor DCPO_ESR register. 


The Bus Error Status Register 0 is part of the decompression core and is addressed indirectly 
through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 
None 
Example 


Retrieve the value of DCPO_ESR register. 


unsigned long current_DCPO_ESR=ppcMfdcp0_esr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfdcp0_id() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcp0_id(void) ; 


Library 

ppcLib.a 

Description 

ppcMfdcp0_id() returns the value of the processor DCP0O_ID compression register. 


The Decompression core ID Register is part of the decompression core and is addressed indirectly 
through the DCPO_CFGADDR and DCP0O_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of DCPO_ID register. 


unsigned long current_DCPO_ID=ppcMfdcp0_id(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdcp0_itor0() - ppcMfdcp0_itor3() -Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcpO0_itor0 (void 
unsigned long ppcMfdcpO_itorl 
unsigned long ppcMfdcpO_itor2 
unsigned long ppcMfdcpO_itor3 


Library 
ppcLib.a 
Description 


ppcMfdcp0_itor0() - ppcMfdcp0_itor3() returns the current value of the specified compression 
Register. 


The Index Table Origin Registers are part of the decompression core and are addressed indirectly 
through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the current value of the DCPO_ITORO register. 


unsigned long dcp0_itor0_value= ppcMfdcp0_itor0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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~Preliminary Copy ppcMfdcp0O_membear‘() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcp0_membear (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdcp0_membear‘() returns the value of the processor DCPO_MEMBEAR compression register. 


The Bus Error Address Register (DCP to EBIU address) is part of the decompression core and is 
addressed indirectly through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of DCPO_MEMBEAR register. 


unsigned long current_DCPO_MEMBEAR=ppcMfdcp0_membear () ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdcp0_plbbear() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcp0_plbbear (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdcp0_plbbear() returns the value of the processor DCPO_PLBBEAR register. 


The Bus Error Address Register (PLB address) is part of the decompression core and is addressed 
indirectly through the DCPO_CFGADDR and DCP0O_CFGDATA registers. 


Errors 


None 


Example 
Retrieve the value of DCPO_PLBBEAR register. 


unsigned long current_DCPO_PLBBEAR=ppcMfdcp0_plbbear () ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfdcp0_ram() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcp0_ram(unsigned long regno) ; 


Library 
ppcLib.a 
Description 


ppcMfdcp0_ram() returns the value of one of the processor DCPO_RAM compression registers, 
specified by regno. There are 0x400 DCPO_RAM registers, from DCPO_RAMO to DCPO_RAMSfF. 
regno must be a value from 0 to Ox3ff. 


The Decompression core SRAM/ROM Registers are part of the decompression core and are 
addressed indirectly through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of DCPO_RAM register 0. 


unsigned long current_DCPO_ROMO=ppcMfdcp0_ram (0) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdcp0_ver‘() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcp0O_ver (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdcp0_ver() returns the value of the processor DCPO_VER register. 


The Decompression core Version Number Register is part of the decompression core and is 
addressed indirectly through the DCPO_CFGADDR and DCP0O_CFGDATA registers. 


Errors 
None 
Example 


Retrieve the value of DCPO_VER register. 


unsigned long current_DCPO_VER=ppcMfdcp0_ver (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfdcwr‘() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdcwr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdewr() returns the value of the processor DCWR (Data Cache Write-through Register). 
Errors 

None 

Example 

Retrieve the value of DCWR register. 


unsigned long current_DCWR=ppcMfdecwr (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdear() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdear (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdear() returns the value of the processor DEAR (Data Exception Address Register). 
Errors 

None 

Example 


Retrieve the value of DEAR register. 


unsigned long current_DEAR=ppcMfdear () ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfdma0_cr0() - ppcMfdma0_cr3() 


Synopsis 


#include <ppcLib.h> 

unsigned long ppcMfdma0_cr0 
unsigned long ppcMfdma0_crl 
unsigned long ppcMfdma0_cr2 
unsigned long ppcMfdma0_cr3 


Library 
ppcLib.a 
Description 


ppcMfdma0_cr0() - ppcMfdma0_cr3() return the value of the DMA channel control registers 
(DMAO_CRO - DMA0_CR3). The DMACRs set up and enables the DMA channels. The file 
<ppcLib.h> contains several constants that can be used when accessing the DMACR’s. 


Errors 

None. 

Example 

Retrieve the current value of the DMAO_CRO. 


unsigned long dmacr0O_value=ppcMfdma0_cr0 (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdma0_ct0() = ppcMfdma0_ct3() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 

unsigned long ppcMfdma0_ct0 (void 
unsigned long ppcMfdma0_ct1 (void 
unsigned long ppcMfdma0_ct2 (void 
unsigned long ppcMfdma0_ct3 (void 


\; 
\; 
3 
\; 
Library 

ppcLib.a 

Description 


ppcMfdma0_ct0() - ppcMfdma0_ct3() return the value of the DMA count registers (DMAQO_CTO - 
DMA0_CT3). The DMACT registers contains the number of transfers left in the DMA transaction for 
the channel. 


Errors 

None. 

Example 

Retrieve the current value of the DMAO_CTO. 


unsigned long dmact0O_value=ppcMfdma0_ct0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfdma0_da0() - ppcMfdma0_da3() 


Synopsis 


#include <ppcLib.h> 

unsigned long ppcMfdma0_da0 
unsigned long ppcMfdma0_dal 
unsigned long ppcMfdma0_da2 
unsigned long ppcMfdma0_da3 


Library 
ppcLib.a 
Description 


ppcMfdma0_da0() - ppcMfdma0_da3() return the value of the DMA destination address registers 
(DMAO_DAO - DMAO_DA3)). The DMADA registers contain the memory addresses for transfers 
between memory and peripheral or the destination addresses for memory to memory transfers. 


Errors 

None. 

Example 

Retrieve an address from DMAO_DAS. 


unsigned long dmada3_value = ppcMfdma0_da3(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdma0_sa0() - ppcMfdma0_sa3() -Preliminary Copy 


Synopsis 


#include <ppcLib.h> 

unsigned long ppcMfdma0_sa0 
unsigned long ppcMfdma0_sal 
unsigned long ppcMfdma0_sa2 
unsigned long ppcMfdma0_sa3 


Library 
ppcLib.a 
Description 


ppcMfdma0_sa0() - ppcMfdma0_sa3() return the value of the DMA source address registers 
(DMAO_SAO - DMAO_SA3). The DMASAs are only used in memory to memory move mode. 


Errors 


None. 


Example 
Retrieve the current value of the DMAO_SAO. 


unsigned long dmasa0_value=ppcMfdma0_sa0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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~Preliminary Copy ppcMfdma0_sg0() - ppcMfdma0_sg3() 


Synopsis 


#include <ppcLib.h> 

unsigned long ppcMfdma0_sg0 
unsigned long ppcMfdma0_sgl 
unsigned long ppcMfdma0_sg2 
unsigned long ppcMfdma0_sg3 


Library 
ppcLib.a 
Description 


ppcMfdma0_sg0() - ppcMfdma0_sg3() return the value of the DMA scatter/gather base address 
registers (DMASBO - DMASB3). The DMASBs contain the address of the current scatter/gather 
descriptor table element in system memory. 


Errors 
None. 
Example 


See “ppcMtdma0_sg0() - pocMtdma0_sg3()” on page 10-171. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfd ma0_sgc() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdma0_sgc (void) ; 


Library 

ppcLib.a 

Description 

ppcMfdma0_sgc() returns the value of the DMA scatter/gather command register (DMAO_SGC). 


The value of the DMAO_SGC may be used when starting or stopping DMA operations on a channel. 
The file <ppcLib.h> contains several constants that may be used when accessing the DMAO_SR . 


Errors 
None. 


Example 


Attributes 


Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 


References 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdma0_sr (void); 


Library 
ppcLib.a 


Description 


ppcMfdma0_sr() 


ppcMfdma0_sr() returns the value of the DMA status register (DMAO_SR). 


The value of the DMAO_SR may be used to determine the status of the DMA channels. The file 
<ppcLib.h> contains several constants that may be used when accessing the DMAO_SR . 


Errors 

None. 

Example 

Retrieve the current value of the DMAO_SR. 


unsigned long dmasr_value=ppcMfdma0_sr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfdvc1() - ppcMfdvc2() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfdvcl (void) 
unsigned long ppcMfdvc2 (void) 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcMfdvc1() - ppcMfdvc2() returns the current value of the specified Data Value Compare Register. 


Errors 

None 

Example 

Retrieve the current value of the DVC2 register. 
unsigned long dvc2_value= ppcMfdvc2(); 
Attributes 

Async Safe 

Cancel Safe 


Interrupt Handler Safe 
Callable from Application Thread Group 


References 
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—Preliminary Copy ppcMfesr‘() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfesr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfesr() returns the value of the processor ESR (Exception Syndrome Register). 
Errors 

None 

Example 


Retrieve the value of ESR register. 


unsigned long current_ESR=ppcMfesr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfevp r() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfevpr (void) ; 


Library 
ppcLib.a 
Description 


ppcMfevpr() returns the value of the processor EVPR (Exception Vector Prefix Register). Bits 0 to 15 
contain the prefix of the address of the exception processing routines. Bits 15 to 31 are reserved. 


Errors 

None 

Example 

Retrieve the value of EVPR register. 


unsigned long current_EVPR=ppcMfevpr () ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfgprt () 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfgpri (void) ; 


Library 

ppcLib.a 

Description 

ppcMfgpr1() returns the current value of GPR(1). 
Typically, this is the value of the current stack frame. 
Errors 

None 

Example 


See “ppcMfgpr2()” on page 10-98. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 
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ppceMfgpr2() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfgpr2 (void) 


Library 
ppcLib.a 
Description 


ppcMfgpr2() returns the current value of GPR(2). 


—Preliminary Copy 


For XCOFF-based OS Open this is typically the value of the table of contents (TOC) pointer for the 


current execution context. 


Errors 


None 


Example 


Retrieve TOC and stack frame base from current context. 


toc = ppcMfgpr2(); 
unsigned long stack_base = ppcMfgpr1(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 
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_Preliminary Copy ppcMfiac1() - ppcMfiac4() 


Synopsis 


#include <ppcLib.h> 

unsigned long ppcMfiacl 
unsigned long ppcMfiac2 
unsigned long ppcMfiac3 
unsigned long ppcMfiac4 


Library 
ppcLib.a 
Description 


ppcMfiac1() - ppcMfiac4() returns the current value of the specified Instruction Address Compare 
Register. The IAC contains the address of the instruction that the debug event will be based on. The 
Debug Control Register 0 (DBCRO) controls the instruction address debug event. Bits 30 and 31 of 
the IAC are reserved, since the address must be word aligned. 


Errors 

None 

Example 

Retrieve the current value of the IAC4 register. 


unsigned long iac4_value= ppcMfiac4(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMficcr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMficcr (void) ; 


Library 

ppcLib.a 

Description 

ppcMficcr() returns the value of the processor ICCR (Instruction Cache Cacheability Register). 
Errors 

None 

Example 

Retrieve the value of ICCR register. 


unsigned long current_ICCR=ppcMficcr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMficdbd r() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMficdbdr (void) ; 


Library 

ppcLib.a 

Description 

ppcMficdbdr() returns the value of the processor ICDBDR (Instruction Cache Debug Data Register). 
<ppc405.h> has constants defined for use with the ICDBDR register. 

Errors 

None 

Example 


Retrieve the value of ICDBDR register. 


unsigned long current_ICDBDR=ppcMficdbdr (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_cfg() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_cfg (void); 


Library 
ppcLib.a 
Description 


ppcMfmal0_cfg() returns the value of the processor MALO_CFG register. 


The MAL Configuration Register is part of the Memory Access Layer core. 


Errors 

None 

Example 

Retrieve the value of the MALO_CFG register. 


unsigned long current_MALO_CFG=ppcMfmal0_cfg(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmal0_esr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_esr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfmal0_esr() returns the value of the processor MALO_ESR register. 
The MAL Error Status Register is part of the Memory Access Layer core. 
Errors 

None 

Example 


Retrieve the value of the MALO_ESR register. 


unsigned long current_MALO_ESR=ppcMfmal0_esr()j; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_ier() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_ier (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_ier() returns the value of the processor MALO_IER register. 

The MAL Interrupt Enable Register is part of the Memory Access Layer core. 
Errors 

None 

Example 


Retrieve the value of the MALO_IER register. 


unsigned long current_MALO_IER=ppcMfmal0O_ier(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmal0_rcbs0() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_rcbs0 (void) ; 


Library 

ppcLib.a 

Description 

ppcMfmal0_rcbs0() returns the value of the processor MALO_RCBSO register. 

The MAL Receive Channel Buffer Size Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_RCBS0O register. 


unsigned long current_MALO_RCBSO=ppcMfmal0_rcbs0 (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_rxcarr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0O_rxcarr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_rxcarr() returns the value of the processor MALO_RXCARR register. 

The MAL RX Channel Active Reset Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_RXCARR register. 


unsigned long current_MALO_RXCARR=ppcMfmal0_rxcarr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmal0_rxcasr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0O_rxcasr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_rxcasr() returns the value of the processor MALO_ register. 

The MAL RX Channel Active Set Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_CASR register. 


unsigned long current_MALO_CASR=ppcMfmal0_rxcasr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_rxctpOr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_rxctpOr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_rxctpOr() returns the value of the processor MALO_RXCTPOR register. 

The MAL RX Channel Table Pointer 0 Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_RXCTPOR register. 


unsigned long current_MALO_RXCTPOR=ppcMfmalO_rxctp0Or(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmal0_rxdeir() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_rxdeir (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_rxdeir() returns the value of the processor MALO_RXDEIR register. 

The MAL RX Descriptor Error Interrupt Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_RXDEIR register. 


unsigned long current_MALO_RXDEIR=ppcMfmal0_rxdeir(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_rxeobisr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_rxeobisr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_rxeobisr() returns the value of the processor MALO_REOBISR register. 

The MAL RX End Of Buffer Interrupt Status Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_REOBISR register. 


unsigned long current_MALO_REOBISR=ppcMfmal0O_rxeobisr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmal0_txcarr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_txcarr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_txcarr() returns the value of the processor MALO_TXCARR register. 

The MAL TX Channel Active Reset Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_TXCARR register. 


unsigned long current_MALO_TXCARR=ppcMfmal0_txcarr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_txcasr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_txcasr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_txcasr() returns the value of the processor MALO_TXCASR register. 
The MAL TX Channel Active Set Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_TXCASR register. 


unsigned long current_MALO_TXCASR=ppcMfmal0_txcasr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmal0_txctpOr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_txctpOr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_txctpOr() returns the value of the processor MALO_TXCTPOR register. 

The MAL TX Channel Table Pointer 0 Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_TXCTPOR register. 


unsigned long current_MALO_TXCTPOR=ppcMfmal0O_txctp0Or(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_txctp1 r() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_txctplr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_txctpir() returns the value of the processor MALO_TXCTP1R register. 

The MAL TX Channel Table Pointer 1 Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_TXCTP1R register. 


unsigned long current_MALO_TXCTP1R=ppcMfmal0O_txctplr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmal0_txdeir() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_txdeir (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_txdeir() returns the value of the processor MALO_TXDEIR register. 

The MAL TX Descriptor Error Interrupt Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_TXDEIR register. 


unsigned long current_MALO_TXDEIR=ppcMfmal0_txdeir(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmal0_txeobisr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmal0_txeobisr (void); 


Library 

ppcLib.a 

Description 

ppcMfmal0_txeobisr() returns the value of the processor MALO_TXEOBISR register. 

The MAL TX End Of Buffer Interrupt Status Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Retrieve the value of the MALO_TXEOBISR register. 


unsigned long current_MALO_TXEOBISR=ppcMfmal0_txeobisr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfmpmit() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_pmit (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsdram0_pmit() returns the value of the processor SDRAMO_PMIT register. 


The Memory Power Management Idle Timer Register is part of the SDRAM controller and is 
addressed indirectly through the SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of SDRAMO_PMIT register. 


unsigned long current_SDRAMO_PMIT=ppcMfsdram0_pmit (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfmsr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfmsr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfmsr() returns the value of the Machine State Register(MSR). 


Refer to the <ppc_arch.h> file for the defines of constants that can be used as masks with the MSR 
value. 


Errors 
None 
Example 


See “pocMtmsr()” on page 10-195. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfocm0_dsarc() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfocm0_dsarc (void) ; 


Library 

ppcLib.a 

Description 

ppcMfocm0_dsarc() returns the value of the processor OCM0_DSARC register. 

The On-Chip Memory Data Side Address Range Compare Register is part of the OCM core. 
Errors 

None 

Example 

Retrieve the value of OCMO_DSARC register. 


unsigned long current_OCM0O_DSARC=ppcMfocm0_dsarc(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfocm0_dscnitl() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfocm0_dscnt1 (void) ; 


Library 

ppcLib.a 

Description 

ppcMfocm0_dscntl() returns the value of the processor OCMO_DSCNTL register. 
The On-Chip Memory Data Side Control Register is part of the OCM core. 

Errors 

None 

Example 

Retrieve the value of OCMO_DSCNTL register. 


unsigned long current_OCM0O_DSCNTL=ppcMfocm0_dscnt1(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfocm0_isarc() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfocm0_isarc (void); 


Library 

ppcLib.a 

Description 

ppcMfocm0_isarc() returns the value of the processor OCMO_ISARC register. 

The On-Chip Memory Instruction Side Address Range Compare Register is part of the OCM core. 
Errors 

None 

Example 

Retrieve the value of OCMO_ISARC register. 


unsigned long current_OCM0O_ISARC=ppcMfocm0_isarc(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfocm0_iscnitl() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfocm0_iscnt1l (void); 


Library 
ppcLib.a 


Description 


ppcMfocm0_iscntl() returns the value of the processor OCMO_ISCNTL register. 


The On-Chip Memory Instruction Side Control Register is part of the OCM core. 
Errors 

None 

Example 

Retrieve the value of OCM0O_ISCNTL register. 


unsigned long current_OCMO_ISCNTL=ppcMfocm0_iscnt1(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfpid() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfpid(void) ; 


Library 

ppcLib.a 

Description 

ppcMfpid() returns the value of the processor PID (Process ID) register. 
Errors 

None 

Example 

Retrieve the value of PID register. 


unsigned long current_PID=ppcMfpid(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfpit() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfpit (void); 


Library 

ppcLib.a 

Description 

ppcMfpit() returns the value of the processor PIT (Programmable Interval Timer) register. 
Errors 

None 

Example 

Retrieve the value of PIT register. 


unsigned long current_PIT=ppcMfpit (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfpvr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfpvr (void) ; 


Library 
ppcLib.a 
Description 


ppcMfpvr() returns the value of the processor version register, which indicates the version and 
revision of the PowerPC processor. 


Errors 
None 
Example 


Retrieve the current value of the processor version register. Processor version-specific code may 
require this value. 


printf(“This is processor version %x\n”, ppcMfpvr()); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfsdram0_bOcr() - ppcMfsdram0_b3cr() 


Synopsis 


#include 
unsigned 
unsigned 
unsigned 
unsigned 


Library 
ppcLib.a 


<ppcLib.h> 

long ppcMfsdram0_bOcr 
long ppcMfsdram0_blcr 
long ppcMfsdram0_b2cr 
long ppcMfsdram0_b3cr 


Description 


—Preliminary Copy 


ppcMfsdram0_bOcr() - ppcMfsdram0_b3cr() returns the current value of the specified register. 


The Memory 0-3 Configuration Registers are part of the SDRAM controller and are addressed 


indirectly through the SPBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 


None 


Example 


Retrieve the current value of the mbOcf register. 


unsigned long mbOcf_value= ppcMfsdram0_b0cr(); 


Attributes 


Async Safe 


Cancel Safe 


Interrupt Handler Safe 


Callable from Application Thread Group 


References 
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-Preliminary Copy ppcMfsdram0_bear() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_bear (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsdram0_bear() returns the value of the processorsDRAMO_BEAR register. 


The PLB Master Bus Error Address Register is part of the SDRAM controller and is addressed 
indirectly through the SBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value ofSDRAMO_BEAR register. 


unsigned long current_BEAR=ppcMfsdram0_bear (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfsdram0_besr0() - ppcMfsdram0_besr1() -Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_besr0 (void) 
unsigned long ppcMfsdram0_besrl (void) 


Library 

ppcLib.a 

Description 

ppcMfsdram0_besr0() - ppcMfsdram0_besr1() returns the current value of the specified Register. 


The Bus Error Syndrome Registers A and B are part of the SDRAM controller and are addressed 
indirectly through the SDBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the current value of the besra register. 


unsigned long besra_value= ppcMfsdram0_besr0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMfsdram0_cfg() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_cfg(void); 


Library 

ppcLib.a 

Description 

ppcMfsdram0_cfg() returns the value of the processor SDRAMO_CFG register. 


The Memory Controller Options 1 Register is part of the SDRAM controller and is addressed 
indirectly through the SBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of SDRAMO_CFG register. 


unsigned long current_SDRAMO_CFG=ppcMfsdram0_cfg(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfsd ram0_ecccfg () —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_ecccfg (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsdram0_ecccfg() returns the value of the processor SDRAMO_ECCCFG register. 


The ECC Configuration Register is part of the SDRAM controller and is addressed indirectly through 
the SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of SDRAMO_ECCCFG register. 


unsigned long current_SDRAMO_ECCCFG=ppcMfsdram0_ecccfg(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMfsdram0_eccesr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_eccesr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsdram0_eccesr() returns the value of the processor SDRAMO_ECCESR register. 


The ECC Error Status Register is part of the SDRAM controller and is addressed indirectly through 
the SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of SDRAMO_ECCESR register. 


unsigned long current_SDRAMO_ECCESR=ppcMfsdram0_eccesr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfsd ram0O_rtr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_rtr (void); 


Library 

ppcLib.a 

Description 

ppcMfsdram0_rtr() returns the value of the processorSDRAMO_RTR register. 


The Refresh Timer Register is part of the SDRAM controller and is addressed indirectly through the 
SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 
None 


Example 
Retrieve the value ofhSDRAMO_RTR register. 


unsigned long current_RTR=ppcMfsdram0_rtr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMfsdram0_tr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsdram0_tr (void); 


Library 

ppcLib.a 

Description 

ppcMfsdram0_tr() returns the value of the processor SDRAMO_TR register. 


The SDRAM Timing Register 1 is part of the SDRAM controller and is addressed indirectly through 
the SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Retrieve the value of SDRAMO_TR register. 


unsigned long current_SDRAMO_TR=ppcMfsdram0_tr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User’s Manual 


Revised 8/22/00 v. 0.8 OS Open Function Reference 10-133 


ppcMfsg r() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsgr (void); 


Library 

ppcLib.a 

Description 

ppcMfsgr() returns the value of the processor SGR (Storage Guarded Register). 
Errors 

None 

Example 

Retrieve the value of SGR register. 


unsigned long current_SGR=ppcMfsgr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfsler() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsler (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsler() returns the value of the processor SLER (Storage Little-Endian Register). 
Errors 

None 

Example 


Retrieve the value of SLER register. 


unsigned long current_SLER=ppcMfsler (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfsprg0() - ppcMfsprg7() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsprg0 
unsigned long ppcMfsprgl 
unsigned long ppcMfsprg2 
unsigned long ppcMfsprg3 
unsigned long ppcMfsprg4 
unsigned long ppcMfsprg5 
unsigned long ppcMfsprg6 
unsigned long ppcMfsprg7 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcMfsprg0() - ppcMfsprg7() returns the current value of the special purpose register generals 


(SPRGO - SPRG7). 


Typically, the SPRGs provide temporary storage at the operating system level. 


NOTE: OS Open reserves SPRGO-3 for its own use. 
Errors 

None 

Example 

Read value of SPRGO. 


unsigned long sprgO_value = ppcMfsprg0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfsrr0() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsrr0 (void) ; 


Library 
ppcLib.a 
Description 


ppcMfsrr0() returns the value of SRRO. 


Typically, SRRO is used in interrupt handlers, as it usually contains the address of the next instruction 
to be executed at the time of the interrupt. SRRO and SRRi1 are set when a noncritical interrupt 


occurs. 


Errors 


None 


Example 


Retrieve the current value of the SRRO. An exception handler may use this value to determine the 


point of exception. 


unsigned long current_srr0=ppcMfsrr0(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfsrr1 () —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsrril (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsrr1() returns the current value of SRR1. 


Typically, SRR1 is used in interrupt handlers, as it contains the old MSR value as well as information 
bits specific to the interrupt. SRRO and SRR1 are set when a noncritical interrupt occurs. 


Errors 
None 
Example 


Retrieve the current value of SRR1. This register contains the saved MSR, which may be needed by 
an exception handler. 


unsigned long current_srrl=ppcMfsrrl(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 


unsigned long ppcMfsrr2 (void) ; 


Library 
ppcLib.a 


Description 


ppcMfsrr2() returns the current value of SRR2. 


ppcMfsrr2() 


Typically, SRR2 is used in interrupt handlers, as it usually contains the address of the next instruction 
to be executed at the time of the interrupt. SRR2 and SRR@ are set when a critical interrupt occurs. 


Errors 


None 


Example 


Retrieve the current value of SRR2. An exception handler may use this value to determine the point of 


exception. 


unsigned long current_srr2=ppcMfsrr2(); 


Attributes 


Async Safe 
Cancel Safe 


Interrupt Handler Safe 


Callable from Application Thread Group 


References 
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ppcMfsrr3() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsrr3 (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsrr3() returns the current value of SRR3. 


Typically, SRR3 is used in interrupt handlers, as it contains the old MSR value as well as information 
bits specific to the interrupt. SRR2 and SRR@ are set when a critical interrupt occurs. 


Errors 
None 
Example 


Retrieve the current value of SRR3. This register contains the saved MSR, which may be needed by 
an exception handler. 


unsigned long current_srr3=ppcMfsrr3(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfsu0r() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfsu0r (void) ; 


Library 

ppcLib.a 

Description 

ppcMfsu0r() returns the value of the processor SUOR (Storage User-Defined 0 Register). 
On the PPC405GP, SUOR is used to hold the K bits indicating storage compression. 
Errors 

None 

Example 

Retrieve the value of SUOR register. 


unsigned long current_SU0OR=ppcMfsu0r(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMftb() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMftb(tb_t *clock_data) ; 


Library 

ppcLib.a 

Description 

ppcMftb() returns the current time base data. 

Typically, the time base registers are used to determine the number of clock cycles that have passed. 
Errors 

None 

Example 

Retrieve the current value of time base high and low registers. 


tb_t clock_data; 
ppcMftb (&clock_data) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMftcr (void) ; 


Library 
ppcLib.a 


Description 


ppcMftcr() 


ppcMftcr() returns the value of the processor TCR (Timer Control Register). 


File <ppc405.h> defines several constants for the TCR. 


Errors 

None 

Example 

Retrieve the value of TCR register. 


unsigned long current_TCR=ppcMftcr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMftsr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMftsr (void) ; 


Library 

ppcLib.a 

Description 

ppcMftsr() returns the value of the processor TSR (Timer Status Register). 
File <ppc405.h> defines several constants for the TSR. 

Errors 

None 

Example 

Retrieve the value of TSR register. 


unsigned long current_TSR=ppcMftsr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfuicO_cr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfuicO_cr (void); 


Library 

ppcLib.a 

Description 

ppcMfuicO_cr() returns the value of the processor UICO_CR register. 
The UIC Critical Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Retrieve the value of UICO_CR register. 


unsigned long current_UICO_CR=ppcMfuic0O_cr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfuicO_er() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfuicO_er (void); 


Library 

ppcLib.a 

Description 

ppcMfuicO_er() returns the value of the processor UICO_ER register. 
The UIC Enable Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 


Retrieve the value of UICO_ER register. 


unsigned long current_UICO_ER=ppcMfuic0O_er(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfuicO_msr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfuicO_msr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfuicO_msr() returns the value of the processor UICO_MSR register. 

The UIC Masked Status Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Retrieve the value of UICO_MSR register. 


unsigned long current_UICO_MSR=ppcMfuicO_msr()j; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfuicO_pr‘() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfuicO_pr (void); 


Library 

ppcLib.a 

Description 

ppcMfuic0_pr() returns the value of the processor UICO_PR register. 
The UIC Polarity Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Retrieve the value of UICO_PR register. 


unsigned long current_UICO_PR=ppcMfuic0O_pr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfuicO_sr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfuicO_sr (void); 


Library 

ppcLib.a 

Description 

ppcMfuic0_sr() returns the value of the processor UICO_SR register. 
The UIC Status Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Retrieve the value of UICO_SR register. 


unsigned long current_UICO_SR=ppcMfuicO_sr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfuicO_tr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfuicO_tr (void); 


Library 

ppcLib.a 

Description 

ppcMfuic0_tr() returns the value of the processor UICO_TR register. 

The UIC Triggering Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Retrieve the value of UICO_TR register. 


unsigned long current_UICO_TR=ppcMfuicO_tr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMfuicO_vr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfuicO_vr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfuicO_vr() returns the value of the processor UICO_VR register. 
The UIC Vector Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Retrieve the value of UICO_VR register. 


unsigned long current_UICO_VR=ppcMfuic0O_vr(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMfzpr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcMfzpr (void) ; 


Library 

ppcLib.a 

Description 

ppcMfzpr() returns the value of the processor ZPR (Zone Protection Register). 
Errors 

None 

Example 

Retrieve the value of ZPR register. 


unsigned long current_ZPR=ppcMfzpr (); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtccr0() 


Synopsis 


#include <ppcLib.h> 
void ppcMtccr0 (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtccr0() sets the value of the processor ccr0 register (Core Configuration Register 0). 
Errors 

None 

Example 

Set the value of ccrO register. 


pecMtccr0 (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtcpc0_cr0() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtcpcO_cr0 (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtcpc0_cr0() sets the value of the processor CPCO_CRO (chip control 0) register. 
Errors 

None 

Example 

Set the value of CPCO_CRO register. 


pepcMtcpcO0_cr0 (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtcpco_cr1 () 


Synopsis 


#include <ppcLib.h> 
void ppcMtcpcO_crl(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtcpc0_cr1() sets the value of the processor CPCO_CR1 (chip control 1) register. 
Errors 

None 

Example 

Set the value of CPCO_CR1 register. 


pecMtcpcO_cri1 (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdact1 ()- ppcMtdac2() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdacl (unsigned long value) 
void ppcMtdac2 (unsigned long value) 


Library 

ppcLib.a 

Description 

ppcMtdac1() - ppcMtdac2() sets the value of the specified register. 


The Data Address Compare registers 1 and 2 contain addresses for which debug events may be 
taken, depending on the values set in the DBCR1 register. 


Errors 

None 

Example 

Set the value of the DAC2 register. 
ppcMtdac2(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User's Manual 


10-156 | PPC405GP Reference Design Kit User's Manual v. 0.8 Revised 8/22/00 


-Preliminary Copy ppcMtdbcr0() - ppcMtdbcr1() 


Synopsis 


#include <ppcLib.h> 
void ppcMtdbcr0 (unsigned long value) 
void ppcMtdbcril (unsigned long value) 


Library 

ppcLib.a 

Description 

ppcMtdbcr0() - ppcMtdbcr1() sets the value of the specified register. 


Dedug Control Registers 0 and 1 are used to enable debug events, reset the processor and set the 
debug mode of the processor. 


WARNING: Enabling bits 0 and 1 can cause unexpected results. Enabling bits 2 and 3 will cause a 
processor reset to occur. DBCRO and DBCR?1 are designed to be used by development tools, not 
applications. 


Refer to the file <ppc405.h> for defined constants for the DBCRO and DBCR? registers. 
Errors 

None 

Example 

Set the value of the DBCR1 register. 

ppcMtdbcr1(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtd bsr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdbsr (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtdbsr() sets the value of the processor DBSR register. 

The Debug Status Register contains the status of debug events and the most recent reset. 
The file <ppc405.h> defines constants that can be used when referring to the DBSR. 
Errors 

None 

Example 

Set the value of DBSR register. 


ppcMtdbsr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtdccr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtdccr (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtdccr‘() sets the value of the processor DCCR (Data Cache Cacheability Register). 
Errors 

None 

Example 

Set the value of DCCR register. 


ppcMtdccr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdcp0_addr0() - ppcMtdcp0O_addr1() -Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdcp0O_addr0O (unsigned long value) 
void ppcMtdcp0O_addri(unsigned long value) 


Library 

ppcLib.a 

Description 

ppcMtdcp0_addr0() - ppcMtdcp0O_addr1() sets the value of the specified register. 


The Address Decode Definition Registers are part of the decompression core and are addressed 
indirectly through the DCPO_CFGADDR and DCP0O_CFGDATA registers. 


Errors 

None 

Example 

Set the value of the DCPO_ADDRO register. 
ppcMtdcp0_addr0(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtdcp0_cfg () 


Synopsis 


#include <ppcLib.h> 
void ppcMtdcp0_cfg(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtdcp0_cfg() sets the value of the processor DCPO_CFG compression register. 


The Decompression core Configuration Register is part of the decompression core and is addressed 
indirectly through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of DCPO_CFG register. 


pecMtdcp0_cfg(value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdcp0 _esr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdcp0_esr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtdcp0_esr() sets the value of the processor DCPO_ESR register. 


The Bus Error Status Register 0 is part of the decompression core and is addressed indirectly 
through the DCPO_CFGADDR and DCPO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of DCPO_ESR register. 


pepcMtdcpO0_esr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMtdcp0_itor0() - ppcMtdcp0_itor3() 


Synopsis 


#include <ppcLib.h> 
void ppcMtdcp0_itor0d 
void ppcMtdcp0_itor1l 
void ppcMtdcp0_itor2 
void ppcMtdcp0_itor3 


unsigned long value 
unsigned long value 
unsigned long value 
unsigned long value 


~~ 
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Library 

ppcLib.a 

Description 

ppcMtdcp0_itor0() - ppcMtdcp0_itor3() sets the value of the specified compression Register. 


The Index Table Origin Registers are part of the decompression core and are addressed indirectly 
through the DCPO_CFGADDR and DCP0O_CFGDATA registers. 


Errors 

None 

Example 

Set the value of the DCPO_ITORDO register. 
ppcMtdcp0_itor0(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdcp0_ram() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdcp0O_ram(unsigned long regno, unsigned long value); 


Library 
ppcLib.a 
Description 


ppcMtdcp0_ram() sets the value of one of the processor DCPO_RAM compression registers, 
specified by regno. There are 0x400 DCPO_RAM registers, from DCPO_RAM0 to DCPO_RAMSff. 
regno must be a value from 0 to Ox3ff. 


The Decompression core SRAM/ROM Registers are part of the decompression core and are 
addressed indirectly through the DCPO_CFGADDR and DCP0O_CFGDATA registers. 


Errors 

None 

Example 

Set the value of DCPO_RAM register 0. 


pecMtdcpO_ram(0,value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtdcwr‘() 


Synopsis 


#include <ppcLib.h> 
void ppcMtdcewr (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtdcewr() sets the value of the processor DCWR (Data Cache Write-through Register). 
Errors 

None 

Example 

Set the value of DCWR register. 


ppcMtdcwr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdear() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdear (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtdear‘() sets the value of the processor DEAR (Data Exception Address Register). 
Errors 

None 

Example 

Set the value of DEAR register. 


ppcMtdear (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtdma0_cr0() - ppcMtdma0_cr3() 


Synopsis 


#include <ppcLib.h> 
void ppcMtdma0_cr0O (unsigned long value); 
void ppcMtdma0_cril(unsigned long value); 
void ppcMtdma0_cr2 (unsigned long value); 
void ppcMtdma0_cr3(unsigned long value); 


Library 
ppcLib.a 
Description 


ppcMtdma0_cr0() - ppcMtdma0_cr3() set the value of the DMA Channel Control Registers 
(DMAO_CRO - DMAO_CR3). Prior to executing DMA transfers, the control register must be initialized 
and enabled. Constants that may be used when accessing the DMACP’s are obtained by including 
<ppcLib.h>. 


Errors 

None. 

Example 

Disable channel 2. 


pecMtdma0_cr2 (~DMACR_CE) ; 


~~ 
x 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdma0_ct0() = ppcMtdma0_ct3() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdma0_ct0O (unsigned long value); 
void ppcMtdma0_ctl(unsigned long value); 
void ppcMtdma0_ct2 (unsigned long value); 
void ppcMtdma0_ct3(unsigned long value); 


Library 
ppcLib.a 
Description 


ppcMtdma0_ct0() - ppcMtdma0_ct3() set the values of the DMA count registers (DMAO_CTO - 
DMAO_CTS3) to the specified value. The DMACTs contain the number of transfers left ina DMA 
transaction for the channel. The maximum number of transfers is 64K and each transfer can be 1, 2, 
or 4 bytes as programmed in the DMA Channel Control register. 


Errors 

None. 

Example 

Set the DMA0_CTO0 for 64K transfers by setting the DMAO_CTO to 0. 


pecMtdma0_ct0 (0x00000000) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtdma0_da0() - ppcMtdma0_da3() 


Synopsis 


#include <ppcLib.h> 
void ppcMtdma0_da0 (unsigned long value) ; 
void ppcMtdma0_dal (unsigned long value); 
void ppcMtdma0_da2 (unsigned long value); 
void ppcMtdma0_da3 (unsigned long value) ; 


Library 
ppcLib.a 
Description 


ppcMtdma0_da0() - ppcMtdma0_da3() set the values of the DMA destination address registers 
(DMAO_DAO - DMAO_DAS3) to the specified value. The DMADA registers contain the memory address 
for transfers between memory and peripheral or the destination address for memory to memory 
transfers. 


Errors 

None. 

Example 

Set the destination address for a transfer. 


pecMtdma0_da0d (0x00020000) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdma0_sa0() - ppcMtdma0_sa3() -Preliminary Copy 


Synopsis 


#include <ppcLib.h> 

void ppcMtdma0_sa0 (unsigned long value); 
void ppcMtdma0_sal(unsigned long value); 
void ppcMtdma0_sa2 (unsigned long value); 
void ppcMtdma0_sa3(unsigned long value); 


Library 
ppcLib.a 
Description 


ppcMtdma0_sa0() - ppcMtdma0_sa3() set the value of the DMA source address registers 
(DMAO_SAO - DMAO_SA3). The DMASA registers are used in memory-to-memory move mode. 


Errors 

None. 

Example 

Set the source address for a transfer. 


pecMtdma0_sa0 (0x00020000) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User's Manual 


10-170 | PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


—Preliminary Copy ppcMtdma0_sg0() - ppcMtdma0_sg3() 


Synopsis 


#include <ppcLib.h> 

void ppcMtdma0_sg0 (unsigned long value); 
void ppcMtdma0_sgl (unsigned long value); 
void ppcMtdma0_sg2 (unsigned long value) 
void ppcMtdma0_sg3 (unsigned long value) 


, 


Library 
ppcLib.a 
Description 


ppcMtdma0_sg0() - ppcMtdma0_sg3() set the value of the DMA scatter/gather base address 
registers (DMASBO - DMASB3). The DMASB registers contain the address of the current 
scatter/gather descriptor table element in system memory. The definition of the scatter/gather 
descriptor table is obtained by including <ioLib.h>. 


Errors 


None. 


Example 
Set up a scatter/gather descriptor table element for a transfer. 


#include <ppcLib.h> 
#include <ioLib.h> 
struct dma_sg_t sg; 
extern unsigned long mysourceaddr, mydestaddr, data_len; 


sg.dmacr_reg=DMACR_EN | DMACR_PW_32; /* Set DMACR values as needed */ 
sg.source_addr=mysourceaddr; /* set source address */ 
sg.dest_addr=mydestaddr; /* set destination address */ 

sg.count=data_len; /* set length of data to be transferred */ 
sg.flags.link=0; /* This is the last scatter/gather element in the list */ 
sg.flags.int_enable=DMA_SG_INT_ERROR; /* enable interrupts for errors only */ 
sg.flags.sub_channel=0; /* set sub_channel =0 */ 

ppcMtdma0_sg0(&sg); /* Set up the address of the table in scatter/gather reg 
*/ 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtd ma0_sgc() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdma0_sgc (unsigned long value); 


Library 
ppcLib.a 
Description 


ppcMtdma0_sgc() sets the value of the DMA Scatter/Gather Command Register (DMAO_SGC). 
Constants that may be used when accessing the DMAO_SGC are obtained by including <ppcLib.h>. 


Errors 
None. 
Example 


Start DMA Scatter/gatehr on channel 2. 


pecMtdmasgce (ppcMfdma0_sgc () | DMAO_SGC_SSG2) ; 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtd ma0_sr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtdma0_sr(unsigned long value); 


Library 
ppcLib.a 
Description 


ppcMtdma0_sr() sets the value of the DMA Status Register (DMAO_SR). Bits in the DMASR may be 
cleared by writing a 1 to the corresponding bit position. The file <ppcLib.h> contains several 
constants that may be used when accessing the DMAO_SR. 


Errors 

None. 

Example 

Set all status bits for channel 3. 


ppcMtdma0_sr (DMAO_SR_ALL3) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtdvct1 ()- ppcMtdvc2() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtdvcl (unsigned long value) 
void ppcMtdvc2 (unsigned long value) 


Library 

ppcLib.a 

Description 

ppcMtdvc1() - ppcMtdvc2() sets the value of the specified Data Value Compare Register. 
Errors 

None 

Example 

Set the value of the DVC2 register. 

ppcMtdvc2(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtesr‘() 


Synopsis 


#include <ppcLib.h> 
void ppcMtesr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtesr‘() sets the value of the processor ESR (Exception Syndrome Register). 
Errors 

None 

Example 

Set the value of ESR register. 


ppcMtesr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtevp r() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtevpr (unsigned long value); 


Library 
ppcLib.a 
Description 


ppcMtevpr() sets the value of the processor EVPR (Exception Vector Prefix Register). Bits 0 to 15 
contain the prefix of the address of the exception processing routines. Bits 15 to 31 are reserved. 


Errors 

None 

Example 

Set the value of EVPR register. 


ppcMtevpr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User's Manual 


10-176 | PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


-Preliminary Copy ppcMtiac1() - ppcMtiac4() 


Synopsis 


#include <ppcLib.h> 

void ppcMtiacl (unsigned long value 
void ppcMtiac2 (unsigned long value 
void ppcMtiac3 (unsigned long value 
void ppcMtiac4 (unsigned long value 


~e wre we ewe 


Library 
ppcLib.a 
Description 


ppcMtiac1() - ppcMtiac4() sets the value of the specified Instruction Address Compare Register. The 
IAC contains the address of the instruction that the debug event will be based on. The Debug Control 
Register 0 (DBCRO) controls the instruction address debug event. Bits 30 and 31 of the IAC are 
reserved, since the address must be word aligned. 


Errors 

None 

Example 

Set the value of the IAC4 register. 
ppcMtiac4(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMticcr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMticcr (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMticcr() sets the value of the processor ICCR (Instruction Cache Cacheability Register). 
Errors 

None 

Example 

Set the value of ICCR register. 


pecMticcr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtmal0_cfg () 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_cfg(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_cfg() sets the value of the processor MALO_CFG register. 
The MAL Configuration Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_CFG register. 


ppcMtmal0_cfg(value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtmal0_esr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_esr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_esr() sets the value of the processor MALO_ESR register. 
The MAL Error Status Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_ESR register. 


ppcMtmal0_esr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtmal0_ier() 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_ier(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_ier() sets the value of the processor MALO_IER register. 

The MAL Interrupt Enable Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_IER register. 


pecMtmal0_ier (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtmal0_rcbs0() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0O_rcbs0O (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_rcbs0() sets the value of the processor MALO_RCBSO register. 

The MAL Receive Channel Buffer Size Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_RCBSO register. 


pecMtmal0_rcbs0 (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMtmal0_rxcarr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0O_rxcarr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_rxcarr() sets the value of the processor MALO_RXCARR register. 

The MAL RX Channel Active Reset Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_RXCARR register. 


pecMtmal0_rxcarr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtmal0_rxcasr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_rxcasr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_rxcasr() sets the value of the processor MALO_RXCASR register. 

The MAL RX Channel Active Set Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_RXCASR register. 


pecMtmal0_rxcasr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtmal0_rxctpOr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0O_rxctpOr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_rxctpOr() sets the value of the processor MALO_RXCTPOR register. 

The MAL RX Channel Table Pointer 0 Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_RXCTPOR register. 


pecMtmal0_rxctpOr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtmal0_rxdeir() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_rxdeir(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_rxdeir() sets the value of the processor MALO_RXDEIR register. 

The MAL RX Descriptor Error Interrupt Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_RXDEIR register. 


pecMtmal0_rxdeir (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 


ppcMtmal0_rxeobisr‘() 


void ppcMtmal0_rxeobisr (unsigned long value); 


Library 
ppcLib.a 


Description 


ppcMtmal0_rxeobisr() sets the value of the processor MALO_RXEOBISR register. 


The MAL RX End Of Buffer Interrupt Status Register is part of the Memory Access Layer core. 


Errors 

None 

Example 

Set the value of the MALO_RXEOBISR register. 


pecMtmal0_rxeobisr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtmal0_txcarr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_txcarr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_txcarr() sets the value of the processor MALO_TXCARR register. 

The MAL TX Channel Active Reset Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_TXCARR register. 


pecMtmal0_txcarr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtmal0_txcasr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_txcasr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_txcasr() sets the value of the processor MALO_TXCASR register. 

The MAL TX Channel Active Set Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_TXCASR register. 


pecMtmal0_txcasr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtmal0_txctpOr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0O_txctpOr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_txctpOr() sets the value of the processor MALO_TXCTPOR register. 

The MAL TX Channel Table Pointer 0 Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_TXCTPOR register. 


pecMtmal0_txctpOr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtmal0_txctp1r() 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_txctplr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_txctpir() sets the value of the processor MALO_TXCTP1R register. 

The MAL TX Channel Table Pointer 1 Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_TXCTPiR register. 


pecMtmal0_txctplr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtmal0_txdeir() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_txdeir(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_txdeir() sets the value of the processor MALO_TXDEIR register. 

The MAL Descriptor Error Interrupt Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_TXDEIR register. 


pecMtmal0_txdeir (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtmal0_txeobisr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtmal0_teobisr (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmal0_teobisr() sets the value of the processor MALO_TEOBISR register. 

The MAL TX End Of Buffer Interrupt Status Register is part of the Memory Access Layer core. 
Errors 

None 

Example 

Set the value of the MALO_TEOBISR register. 


pecMtmal0_teobisir (value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtm pmit() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_pmit (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsdram0_pmit() sets the value of the processor SDRAMO_PMIT register. 


The Memory Power Management Idle Timer Register is part of the SDRAM controller and is 
addressed indirectly through the SDBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of SDBRAMO_PMIT register. 


pecMtsdram0_pmit (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtmsr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtmsr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtmsr‘() sets the value of the Machine State Register(MSR). 


Refer to the <ppc_arch.h> file for the defines of constants that can be used as masks with the MSR 
value. 


Errors 

None 

Example 

Enable external interrupts: 


unsigned long msr=ppcMfmsr () 
ppcMtmsr (msr | PpCcMsrEE) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtocm0_dsarc() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtocm0_dsarc(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtocm0_dsarc() sets the value of the processor OCM0_DSARC register. 

The On-Chip Memory Data Side Address Range Compare Register is part of the OCM core. 
Errors 

None 

Example 

Set the value of OCM0_DSARC register. 


pecMtocm0_dsarc (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtocm0_dscnil() 


Synopsis 


#include <ppcLib.h> 
void ppcMtocm0_dscntl (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtocm0_dscnitl() sets the value of the processor OCMO_DSCNTL register. 
The On-Chip Memory Data Side Control Register is part of the OCM core. 
Errors 

None 

Example 

Set the value of OCMO_DSCNTL register. 


pecMtocm0_dscntl (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtocm0_isarc() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtocm0_isarc(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtocm0_isarc() sets the value of the processor OCM0_ISARC register. 

The On-Chip Memory InstructionSide Address Range Compare Register is part of the OCM core. 
Errors 

None 

Example 

Set the value of OCMO_ISARC register. 


ppcMtocm0_isarc (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtocm0_iscnitl() 


Synopsis 


#include <ppcLib.h> 
void ppcMtocm0_iscntl (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtocm0_iscntl() sets the value of the processor OCMO_ISCNTL register. 
The On-Chip Memory InstructionSide Control Register is part of the OCM core. 
Errors 

None 

Example 

Set the value of OCMO_ISCNTL register. 


pepcMtocm0_iscntl (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppeMtpid() 


Synopsis 


#include <ppcLib.h> 
void ppcMtpid(unsigned long value); 


Library 
ppcLib.a 


Description 


ppcMtpid() sets the value of the processor PID (Process ID) register. 


Errors 

None 

Example 

Set the value of PID register. 


pecMtpid (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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Revised 8/22/00 


—Preliminary Copy ppcMtpit() 


Synopsis 


#include <ppcLib.h> 
void ppcMtpit (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtpit() sets the value of the processor PIT (Programmable Interval Timer) register. 
Errors 

None 

Example 

Set the value of PIT register. 


pecMtpit (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtsdram0_bOcr() - ppcMtsdram0_b3cr() -Preliminary Copy 


Synopsis 


#include <ppcLib.h> 

void ppcMtsdram0_bOcr (unsigned long value 
void ppcMtsdram0_blcr (unsigned long value 
void ppcMtsdram0_b2cr (unsigned long value 
void ppcMtsdram0_b3cr (unsigned long value 


~e wre we owas 


Library 

ppcLib.a 

Description 

ppcMtsdram0_b0cr() - ppcMtsdram0_b3cr() sets the value of the specified register. 


The Memory 0-3 Configuration Registers are part of the SDRAM controller and are addressed 
indirectly through the SDBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of the mbOcf register. 


ppcMtsdram0_b0cr(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMtsdram0_bear() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_bear (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsdram0_bear() sets the value of the processorSsDRAMO_BEAR register. 


The PLB Master Bus Error Address Register is part of the SDRAM controller and is addressed 
indirectly through the SBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value ofSDRAMO_BEAR register. 


ppcMtsdram0_bear (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtsdram0_besr0() - ppcMtsdram0_besr1() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_besr0 (unsigned long value) 
void ppcMtsdram0_besril (unsigned long value) 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcMtsdram0_besr0() - ppcMtsdram0_besr1() sets the value of the specified Register. 


The Bus Error Syndrome Registers A and B are part of the SDRAM controller and are addressed 


indirectly through the SDBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of the SDBRAMO_BESRO register. 
ppcMtsdram0_besr0(value); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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Revised 8/22/00 


-Preliminary Copy ppcMtsdram0_cfg() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_cfg(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsdram0_cfg() sets the value of the processor SDRAMO_CFG register. 


The Memory Controller Options 1 Register is part of the SDRAM controller and is addressed 
indirectly through the SBRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of SDRAMO_CFG register. 


ppcMtsdram0_cfg(value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtsd ram0_ecccfg () —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_ecccfg(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsdram0_ecccfg() sets the value of the processor SDRAMO_ECCCFG register. 


The ECC Configuration Register is part of the SDRAM controller and is addressed indirectly through 
the SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of SDBRAMO_ECCCFG register. 


ppcMtsdram0_ecccfg (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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-Preliminary Copy ppcMtsdram0_eccesr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_eccesr (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsdram0_eccesr() sets the value of the processor SDRAMO_ECCESR register. 


The ECC Error Status Register is part of the SDRAM controller and is addressed indirectly through 
the SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of SPBRAMO_ECCESR register. 


pecMtsdram0_eccesr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtsd ram0O_rtr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_rtr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsdram0_rtr() sets the value of the processorSDRAMO_RTR register. 


The Refresh Timer Register is part of the SDRAM controller and is addressed indirectly through the 
SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value ofSDRAMO_RTR register. 


pecMtsdram0_rtr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtsd ram0O_tr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsdram0_tr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsdram0_tr() sets the value of the processor SDRAMO_TR register. 


The SDRAM Timing Register 1 is part of the SDRAM controller and is addressed indirectly through 
the SDRAMO_CFGADDR and SDRAMO_CFGDATA registers. 


Errors 

None 

Example 

Set the value of SDRAMO_TR register. 


ppcMtsdram0_tr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtsg r() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtsgr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsgr() sets the value of the processor SGR (Storage Guarded Register). 
Errors 

None 

Example 

Set the value of SGR register. 


ppcMtsgr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtsler() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsler(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsler() sets the value of the processor SLER (Storage Little-Endian Register). 
Errors 

None 

Example 

Set the value of SLER register. 


ppcMtsler (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppceMtsprg0() - ppcMtsprg7() 


Synopsis 


#include <ppcLib.h> 

void ppcMtsprg0 (unsigned long valu 
void ppcMtsprgl1 (unsigned long valu 
void ppcMtsprg2 (unsigned long valu 
void ppcMtsprg3 (unsigned long valu 
void ppcMtsprg4 (unsigned long valu 
void ppcMtsprg5 (unsigned long valu 
void ppcMtsprg6(unsigned long valu 
void ppcMtsprg7 (unsigned long valu 


Library 
ppcLib.a 


Description 


—Preliminary Copy 


ppcMtsprg0() - ppcMtsprg7() sets the value of the special purpose register generals (SPRGO - 


SPRG7). 


Typically, the SPRGs provide temporary storage at the operating system level. 


NOTE: OS Open reserves SPRGO-3 for its own use. 
Errors 

None 

Example 

Set value of SPRGO. 


pecMtsprg0 (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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Revised 8/22/00 


—Preliminary Copy ppcMtsrr0() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsrr0O (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsrr0() sets the value of SRRO. 


Typically, SRRO is used in interrupt handlers, as it usually contains the address of the next instruction 
to be executed at the time of the interrupt. SRRO and SRR1 are set when a noncritical interrupt 
occurs. 


Errors 

None 

Example 

Set the value of the SRRO. 


ppcMtsrrO(value); 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“ppcMfsrr1()” on page 10-138 
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ppcMtsrr1 () —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtsrrl(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsrr1() sets the value of SRR1. 


Typically, SRR1 is used in interrupt handlers, as it contains the old MSR value as well as information 
bits specific to the interrupt. SRRO and SRR1 are set when a noncritical interrupt occurs. 


Errors 

None 

Example 

Set the value of SRR1. 


ppcMtsrrl (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtsrr2() 


Synopsis 


#include <ppcLib.h> 
void ppcMtsrr2 (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsrr2() sets the value of SRR2. 


Typically, SRR2 is used in interrupt handlers, as it usually contains the address of the next instruction 
to be executed at the time of the interrupt. SRR2 and SRR@ are set when a critical interrupt occurs. 


Errors 

None 

Example 

Set the value of SRR2. 


pecMtsrr2 (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtsrr3() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtsrr3 (unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtsrr3() sets the value of SRR3. 


Typically, SRR3 is used in interrupt handlers, as it contains the old MSR value as well as information 
bits specific to the interrupt. SRR2 and SRR@ are set when a critical interrupt occurs. 


Errors 

None 

Example 

Set the value of SRR3. 


pecMtsrr3 (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtsu0r (unsigned long value); 


Library 
ppcLib.a 


Description 


ppcMtsu0r() sets the value of the processor SUOR (Storage User-Defined 0 Register). 


ppcMtsu0r() 


On the PPC405GP, SUOR is used to hold the K bits indicating storage compression. 


Errors 

None 

Example 

Set the value of SUOR register. 


pecMtsu0r (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMttb() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMttb(tb_t *clock_data); 


Library 

ppcLib.a 

Description 

ppcMttb() sets the time base data. 

Typically, the time base registers are used to determine the number of clock cycles that have passed. 
Errors 

None 

Example 

Set the value of time base high and low registers. 


tbh_t clock_data; 
ppcMttb (&clock_data) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMttcr(unsigned long value); 


Library 
ppcLib.a 


Description 


ppcMttcr() 


ppcMttcr() sets the value of the processor TCR (Timer Control Register). 


File <ppc405.h> defines several constants for the TCR. 


Errors 

None 

Example 

Set the value of TCR register. 


ppcMttcr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMttsr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMttsr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMttsr() sets the value of the processor TSR (Timer Status Register). 
File <ppc405.h> defines several constants for the TSR. 

Errors 

None 

Example 

Set the value of TSR register. 


ppcMttsr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtuicO_cr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtuicO_cr() sets the value of the processor UICO_CR register. 

The UIC Critical Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Set the value of UICO_CR register. 


pecMtuicO_cr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtuicO_er() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtuicO_er(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtuic0_er() sets the value of the processor UICO_ER register. 

The UIC Enable Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Set the value of UICO_ER register. 


pecMtuicO_er (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtuicO_pr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtuicO_pr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtuicO_pr() sets the value of the processor UICO_PR register. 

The UIC Polarity Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Set the value of UICO_PR register. 


pecMtuicO_pr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtuicO_sr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtuicO_sr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtuic0_sr() sets the value of the processor UICO_SR register. 

The UIC Status Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Set the value of UICO_SR register. 


pecMtuicO_sr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtuicO_tr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtuic0_tr() sets the value of the processor UICO_TR register. 

The UIC Triggering Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Set the value of UICO_TR register. 


pecMtuicO_tr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcMtu icO_vcr() —Preliminary Copy 


Synopsis 


#include <ppcLib.h> 
void ppcMtuicO_vcer(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtuicvr() sets the value of the processor UICO_VCR register. 

The UIC Vector Configuration Register is part of the Universal Interrupt Controller core. 
Errors 

None 

Example 

Set the value of UICVC register. 


ppcMtuicO_vcr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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—Preliminary Copy ppcMtzpr() 


Synopsis 


#include <ppcLib.h> 
void ppcMtzpr(unsigned long value); 


Library 

ppcLib.a 

Description 

ppcMtzpr() sets the value of the processor ZPR (Zone Protection Register). 
Errors 

None 

Example 

Set the value of ZPR register. 


ppcMtzpr (value) ; 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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ppcOrMsr() 


Synopsis 


#include <ppcLib.h> 
unsigned long ppcOrMsr(unsigned long value); 


Library 
ppcLib.a 


Description 


ppcOrMsr() performs the OR of value and the current MSR, updating the MSR. 


The previous value of the MSR is returned. 


—Preliminary Copy 


The file <ppcLib.h> defines several constants for the MSR that can be used as masks. 


Errors 

None 

Example 

Enable instruction address translation. 


unsigned long old_val = ppcOrMsr (ppcMsrIR) ; 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“ppcAndMsr()” on page 10-58 
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—Preliminary Copy ppcSync() 


Synopsis 


#include <ppcLib.h> 
void ppcSync (void) ; 


Library 
ppcLib.a 


Description 


ppcSync() causes the processor to wait until all data cache lines scheduled to be written to main 


storage have actually been written. 

Errors 

None 

Example 

Ensure a ppcDbci() completes before using the values. 


char *memptr = (char *)0x2000; 
char new_value; 
pecDchi( (void *)memptr) 


ppcsync(); 
new_value = *memptr; 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 
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Ss] dbprintf() —Preliminary Copy 


Synopsis 


#include <sys/asyncLib.h> 
int sldbprintf (unsigned long uart_clock, unsigned char *base_reg, unsigned 
long cpcO_crO_reg, event_t int_level, const char *format,...); 


Library 


asyncLib.a 
Description 


s1dbprintf() is a version of printf() that uses polled writes (no interrupts) to serial port 1, and may be 
used before I/O has been established. s1dbprintf() may be called before the async device driver is 
installed. uart_clock is the clock frequency of the serial port. base_reg specifies the address of the 
base UART register. cpc0O_cr0_reg specifies the fields in the Chip Control 0 register that will be set. 
Only the fields relevant to UART 0 should be specified. int_level specifies the interrupt level 
associated with serial port 1. The default communication values are 9600 baud, 8 bit data, no parity, 1 
stop bit. 


Manifest constants for common values for the parameters are supplied in <sys/asyncLib.h>, 
<ioLib.h> and <ppcLib.h>. To use the external UART clock, uart_clock must be asyncClockRate, 
base_reg must be UARTO_BASE_ ADDRESS, cpc0_cr0_reg must be 
CPCO_CRO_UART0O_EXTCLOCK_EN, int_level must be EXT_IRQ_COM1. 


Errors 

None 

Example 

Print “Hello World” on serial port 1 before I/O has been initialized. 


#include <sys/asyncLib.h> 

#include <ioLib.h> 

#include <ppcLib.h> 

#define S1DB_PARMS asyncClockRate, UARTO_BASE_ADDRESS, 
CPCO_CRO_UARTO_EXTCLOCK_EN, EXT_IRQ_COM1 
sldbprintf(S1DB_PARMS, "Hello World\n\r”); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“vsidbprintf()” on page 10-252 
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s2dbprintf() —Preliminary Copy 


Synopsis 


#include <sys/asyncLib.h> 
int s2dbprintf (unsigned long uart_clock, unsigned char *base_reg, unsigned 
long cpcO_crO_reg, event_t int_level, const char *format,...); 


Library 


asyncLib.a 
Description 


s2dbprintf() is a version of printf() that uses polled writes (no interrupts) to serial port 2, and may be 
used before I/O has been established. s2dbprintf() may be called before the async device driver is 
installed. uart_clock is the clock frequency of the serial port. base_reg specifies the address of the 
base UART register. cpcO_cr0_reg specifies the fields in the Chip Control 0 register that will be set. 
Only the fields relevant to UART 1 should be specified. int_level specifies the interrupt level 
associated with serial port 2. The default communication values are 9600 baud, 8 bit data, no parity, 1 
stop bit. 


Manifest constants for common values for the parameters are supplied in <sys/asyncLib.h>, 
<ioLlb.h> and <ppcLib.h>. To use the external UART clock, uart_clock must be asyncClockRate, 
base_reg must be UART1_BASE_ ADDRESS, cpc0_cr0_reg must be 
CPCO_CRO_UART1_EXTCLOCK_EN, int_level must be EXT_IRQ_COM2. 


Errors 

None 

Example 

Print “Hello World” on serial port 2 before I/O has been initialized. 


#include <sys/asyncLib.h> 

#include <ioLib.h> 

#include <ppcLib.h> 

#define S2DB_PARMS asyncClockRate, UART1_BASE_ADDRESS, 
CPCO_CRO_UART1_EXTCLOCK_EN, EXT_IRQ_COM2 

s2dbprintf (S2DB_PARMS, "Hello World\n\r”); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User's Manual 
PowerPC 405 Reference Board Manual 
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—Preliminary Copy ti mebase_speed () 


Synopsis 


#include <tickLib.h> 
unsigned long timebase_speed (void) ; 


Library 
tickLib.a 
Description 


timebase_speed() returns the timebase frequency, in Hz. This is done by setting serial port 2 toa 
known speed (9600 bps) in loopback mode and sending a character out to it. This takes a known 
amount of time for the character to be received. By determining how many increments to the timebase 
registers occurred during this known time, the timebase frequency can be determined. 


Errors 
None 
Example 


Get the timebase speed. 


unsigned long tbh_speed=timebase_speed(); 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


PPC405GP Embedded Controller User’s Manual 
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timertick_install() 


Synopsis 


#include <tickLib.h> 
int timertick_install (void); 


Library 
tickLib.a 


Description 


—Preliminary Copy 


timertick_install() installs and starts the timer tick handler to maintain time-of-day in the OS Open 


real-time executive. 


Errors 


[ENOMEM] Insufficient memory to install the timer tick handler. 


Example 
Do a timertick_install(). 
timertick_install(); 


Attributes 


Async Safe 

Cancel Safe 

Interrupt Handler Safe 

Callable from Application Thread Group 


References 


“timertick_remove()” on page 10-235 


Yes 
Yes 
Yes 
No 
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—Preliminary Copy timertick_remove() 


Synopsis 


#include <tickLib.h> 
int timertick_remove( void ); 


Library 
tickLib.a 
Description 


timertick_remove() removes the timer tick handler installed by timertick_install(). 


Errors 

[EINVAL] Internal error involving tick handler level. 
Attributes 

Async Safe Yes 

Cancel Safe Yes 

Interrupt Handler Safe Yes 

Callable from Application Thread Group No 

References 


“timertick_install()” on page 10-234 
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vga_cls() —Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
void vga_cls( void ); 


Library 
vgaLib.a 
Description 


vga_cls() clears the VGA screen. In text mode, the cursor position is reset to the top left corner of the 
screen (coordinates 0,0). 


Text mode: Yes 
Graphics mode: Yes 


Errors 

None. 
Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_set_mode()” on page 10-248 
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—Preliminary Copy vga_fill_block() 


Synopsis 


#include <sys/vgaLib.h> 
int vga_fill_block( unsigned int x, unsigned int y, 
unsigned int width, unsigned int height, int color ); 


Library 
vgaLib.a 
Description 


vga_fill_ block() fills a rectangular block with color. The block has its top left corner at cordinates x,y, 
and is of width width and height height. 


Returns 0 if successful. 


Text mode: No 
Graphics mode: Yes 


Errors 


Returns -1 if the block extends beyond the screen size, or if the VGA display is not in graphics mode. 


Attributes 

Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_set_pixel()” on page 10-249 
“vga_write_data()” on page 10-250 
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vga_get_cursor_info() —Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
int vga_get_cursor_info( struct vga_cursor_info_t* cursor ); 


Library 
vgaLib.a 
Description 


vga_get_cursor_info() retrieves information about the current position and state of the cursor. The x 
and y coordinates of the cursor are returned in cursor->x and cursor->y respectively. The cursor type 
is returned in cursor->type, and may have the value VGA_CURSOR_BLOCK (block cursor) or 
VGA_CURSOR_UNDERLINE (underline cursor). The cursor state is returned in cursor->state, and 
may have the value VGA_CURSOR_OFF or VGA_CURSOR_ON. 


Returns 0 if successful. 


Text mode: Yes 
Graphics mode: No 


Errors 
Returns -1 if VGA display is not in text mode. 
Example 


See “vga_set_cursor_info()” on page 10-247. 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_set_cursor_info()” on page 10-247 
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—Preliminary Copy vga_get_screen_dimensions() 


Synopsis 


#include <sys/vgaLib.h> 
void vga_get_screen_dimensions( struct vga_pos* dim, int* num_colors ); 


Library 
vgaLib.a 
Description 


vga_get_screen_dimensions() retrieves the current screen size and the number of colors 
supported. The screen size is returned in dim->x and dim->y. For graphics modes these dimensions 
are in pixels - for text mode they are in characters. The current number of colors supported is returned 
in the variable pointed to by num_colors. 


Text mode: Yes 
Graphics mode: Yes 


Errors 
None. 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_set_mode()” on page 10-248 
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vga_get_vid_mem_start() 


Synopsis 


#include <sys/vgaLib.h> 
char * vga_get_vid_mem_start( void ); 


Library 
vgaLib.a 


Description 


—Preliminary Copy 


vga_get_vid_mem_start() returns a pointer to the memory-mapped address of video memory in the 
current display mode. This can be used to directly access display memory. 


Text mode: Yes 
Graphics mode: Yes 


Errors 
None. 


Attributes 


Async Safe 

Cancel Safe 

Interrupt Handler Safe 

Callable from Application Thread Group 
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—Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
int vga_init( void ); 


Library 
vgaLib.a 


Description 


vga_init() 


vga_init() initialises the Video Graphics Array (VGA) display adapter 


Returns 0 if successful. 

Errors 

Returns -1 if no VGA adapter found. 
Attributes 


Async Safe 
Cancel Safe 
Interrupt Handler Safe 


Callable from Application Thread Group 


References 

“vgadd_init” on page 10-251 
“vga_set_mode()” on page 10-248 
“VGA Support” on page 9-16 
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vga_print_char() —Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
int vga_print_char( char c, unsigned int x, unsigned int y, int attr ); 


Library 

vgaLib.a 

Description 

vga_print_char() prints the character c, with attributes attr at location x,y. 
Returns 0 if successful. 


Text mode: Yes 
Graphics mode: No 


Errors 
Returns -1 if VGA display is not in text mode, of if the position given is outside the display area. 


Attributes 


Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_print_char_at_cursor()” on page 10-243 
“vga_print_string()” on page 10-244 


“vga_print_string_at_cursor()” on page 10-245 
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—Preliminary Copy vga_print_char_at_cursor() 


Synopsis 


#include <sys/vgaLib.h> 
int vga_print_char_at_cursor( char c, int attr ); 


Library 
vgaLib.a 
Description 


vga_print_char_at_cursor‘() prints the character c, with attributes aftr,at the current cursor location. 
The cursor location is advanced one character. If the cursor is located at the last location on the 
screen (bottom right) it wraps to the first position on the bottom line of the screen (bottom left). 


Returns 0 if successful. 


Text mode: Yes 
Graphics mode: No 


Errors 


Returns -1 if VGA display is not in text mode. 


Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_print_char()” on page 10-242 
“vga_print_string()” on page 10-244 


“vga_print_string_at_cursor()” on page 10-245 
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vga_print_string() —Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
int vga_print_string( char* string, unsigned int x, unsigned int y, int attr 


3 

Library 
vgaLib.a 
Description 


vga_print_string() prints the null-terminated character string string, with attributes attr, starting at 
location x, y. 


Returns 0 if successful. 


Text mode: Yes 
Graphics mode: No 


Errors 


Returns -1 if VGA display is not in text mode, of if the position given would cause the string to exceed 
the display area. 


Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_print_char()” on page 10-242 
“vga_print_char_at_cursor()” on page 10-243 


“vga_print_string_at_cursor()” on page 10-245 
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—Preliminary Copy vga_print_string_at_cursor‘() 


Synopsis 


#include <sys/vgaLib.h> 
int vga_print_string_at_cursor( char* string, int attr ); 


Library 
vgaLib.a 
Description 


vga_print_string_at_cursor() prints the null-terminated character string string, with attributes attr, 
starting at the current cursor location. The cursor location is updated to follow the last character 
written. If the last character is written at the last screen position (bottom right), the cursor wraps to the 
start of the bottom line (bottom left). 


Returns 0 if successful. 


Text mode: Yes 
Graphics mode: No 


Errors 


Returns -1 if VGA display is not in text mode, of if the position given would cause the string to exceed 
the display area. 


Attributes 

Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_print_char()” on page 10-242 
“vga_print_char_at_cursor()” on page 10-243 


“vga_print_string()” on page 10-244 
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vga_scroll_ up() —Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
int vga_scroll_up( void ); 


Library 
vgaLib.a 
Description 


vga_scroll_up() scrolls the screen up one line. The top row of the screen is discarded, all other lines 
are moved up 1 line, the bottom line of the screen is cleared. The cursor position remains unchanged 
- it remains at the same position on the screen, it does not follow the data that is scrolled. 


Returns 0 if successful. 


Text mode: Yes 
Graphics mode: No 


Errors 


Returns -1 if VGA display is not in text mode. 


Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
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—Preliminary Copy vga_set_cursor_info() 


Synopsis 


#include <sys/vgaLib.h> 
int vga_set_cursor_info( struct vga_cursor_info_t* cursor ); 


Library 
vgaLib.a 
Description 


vga_set_cursor_info() sets the location of the cursor and the cursor state. The x and y coordinates 
are set to the values specified in cursor->x and cursor->y respectively. The cursor type is set by 
cursor->type, which may have the value V@A_CURSOR_BLOCK (block cursor) or 
VGA_CURSOR_UNDERLINE (underline cursor). The cursor state is set by cursor->state, which may 
have the value VGA_CURSOR_ON or VGA_CURSOR_ OFF. 


Returns 0 if successful. 


Text mode: Yes 
Graphics mode: No 


Errors 

Returns -1 if VGA display is not in text mode or if the position specified is outside the display area. 
Example 

Turn the cursor off. 

#include <sys/vgaLib.h> 


vga_cursor_info_t cursor; 


vga_get_cursor_info(&cursor) ; 
cursor->state=VGA_CURSOR_OFF; 
vga_set_cursor_info(&cursor) ; 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_get_cursor_info()” on page 10-238 
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vga_set_mode() —Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
int vga_set_mode( int mode ); 


Library 

vgaLib.a 

Description 

vga_set_mode() sets the VGA mode as specified in the variable mode. 
Possible values for mode are: 


VGA_MODE_TEXT_80x25: VGA mode 2*. 80x25 character text mode, 16 colors. 
VGA_MODE_GRAPHICS_640x480x16: VGA mode 12h. 640x480 graphics, 16 colors 
VGA_MODE_GRAPHICS_320x200x256: VGA mode 13h. 320x200 graphics, 256 colors 


This does not clear the screen in the new mode. If needed, vga_cls() should be called to clear the 
screen. 


Returns 0 if successful. 
Errors 


Returns -1 if mode is not one of the valid values. 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_cls()” on page 10-236 
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—Preliminary Copy vga_set_pixel() 


Synopsis 


#include <sys/vgaLib.h> 
int vga_set_pixel( unsigned int x, unsigned int y, int color ); 


Library 

vgaLib.a 

Description 

vga_set_pixel() sets one pixel at the specified x,y coordinates to the color color. 
Returns 0 if successful. 


Text mode: No 
Graphics mode: Yes 


Errors 


Returns -1 if VGA display is not in graphics mode, or if the x,y coordinates are outside the display 
area. 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_fill_block()” on page 10-237 
“vga_write_data()” on page 10-250 
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vga_write_data() —Preliminary Copy 


Synopsis 


#include <sys/vgaLib.h> 
int vga_write_data( unsigned int x, unsigned int y, unsigned int length, char 
* data, int packed ); 


Library 
vgaLib.a 
Description 


vga_write_data() writes the data pointed to by data,of length /ength, to the specified x,y coordinates. 
The data can either be in one pixel per byte (packed = VGA_DATA_NOT_PACKED), or, for 4-bit, 16 
color data, packed into nibbles, 2 pixels per byte (packed = VGA_DATA_PACKED). The data is written 
to consecutive addresses, so that when the end of a line is reached the data will wrap and continue 
on the following line. 


Returns 0 if successful. 


Text mode: No 
Graphics mode: Yes 


Errors 


Returns -1 if VGA display is not in graphics mode, or if the either x,y coordinate is outside the display 
area, or if the data written would extend outside the display area. 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_fill_block()” on page 10-237 
“vga_write_data()” on page 10-250 
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—Preliminary Copy vg add_init() 


Synopsis 


#include <sys/vgaLib.h> 
int driver_install( int * devhandle, vgadd_init ); 


Library 
vgaLib.a 
Description 


vgadd_init is the entry point for the VGA device driver. The VGA device driver is installed by calling 
driver_install() with devhandle as the first parameter and vgadd_init as the second parameter. 


Installing the device driver using device_install() and driver_install() will automatically call vga_init(). 
Errors 
None. 


Example 


#include <sys/vgaLib.h> 

#include <sys/devDrivr.h> 

int rc; 

int vgadev; 

rce=driver_install(&vgadev, vgadd_init); 
rc=device_install (“/dev/vgal”, CHRTYPE, vgadev) ; 


Attributes 
Async Safe No 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group Yes 
References 


“vga_init()” on page 10-241 
“VGA device driver” on page 9-20 
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vst dbprintf() —Preliminary Copy 


Synopsis 
#include <sys/asyncLib.h> 


int vsldbprintf (unsigned long uart_clock, unsigned char *base_reg, unsigned 
long cpcO_crO_reg, event_t int_level, const char *format, va_list arg_list); 


Library 


asyncLib.a 


Description 


vsidbprintf() is a version of s1dbprintf() that accepts a va_list as a parameter instead of a variable 
number of parameters. vs1dbprintf() may be called before the async device driver is installed. 
uart_clock is the clock frequency of the serial port. base_reg specifies the address of the base 
UART register. cpcO_cr0_reg specifies the fields in the Chip Control 0 register that will be set. Only 
the fields relevant to UART 0 should be specified. int_level specifies the interrupt level associated 
with serial port 1. arg_list is a list of variable arguments that has been created by a call to va_start(). 
The default communication values are 9600 baud, 8 bit data, no parity, 1 stop bit. 


Errors 
None 
Attributes 
Async Safe Yes 
Cancel Safe Yes 
Interrupt Handler Safe Yes 
Callable from Application Thread Group No 
References 


“sidbprintf()” on page 10-230 
PPC405GP Embedded Controller User's Manual 
PowerPC 405 Reference Board Manual 
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Appendix A. Program Trace Calls 


This appendix describes the remote debugging interface provided by the ROM monitor. These calls 
may be used by remote debuggers other than the RISCWatch debugger provided with the kit. 


A.1. Overview 


The following section describes the message (ptrace) protocol that has been implemented in the 
ROM monitor to support debug. If you want to interface your own debugger to the ROM monitor or 
modify the ROM monitor to interface with your debugger, you will need to understand the existing 
message protocol associated with the various debugging functions. 


The ptrace interface to the ROM monitor can best be understood by reviewing the information below 
along with the debug-specific ROM monitor source code (dbLib/ptrace.c). 


A.2. MSGDATA Structure 


In the interface descriptions shown below, several references are made to a “process id.” The concept 
of process ids does not apply to the ROM monitor, so any nonzero value can be used. The ROM 
monitor uses the value 42. 


Data structure MSGDATA is defined in dog.h. New register definitions and new error messages are 
also defined in dbg.h. 


The dbg.h file is shown below: 


/* @(#)dbg.h4.3 5/9/95 09:12:14 */ 

/* 
| COPYRIGHT IBM CORPORATION 1994 

| LICENSED MATERTAL —- PROGRAM PROPERTY OF I BM 

| REFER TO COPYRIGHT INSTRUCTIONS: FORM G120-2083 

| US Government Users Restricted Rights - Use, duplication or | 
disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 

+ ay 
#if !defined(DBG_H) 

#define DBG_H 

#define BREAKPT 0x7D821008 

#ifndef MIN 


#define MIN(X,Y) ((X) < (Y) ? (X) : (Y)) 

#fendif 

/*ptrace definitions based on AIX ptrace * / 
#define RD_TRACE_ME 0 /* used ONLY by target task to be traced*/ 
#define RD_READ_I 1 /* read target instruction addr space */; 
#define RD_READ_D 2 /* read target data address space * / 
#define RD_READ_U 3 /* read offset from the user structure */ 
#define RD_WRITE_I 4 /* write target instruction addr space */ 
#define RD_WRITE_D 5 /* write target data address space if; 
#define RD_WRITE_U 6 /* write offset to the user structure fh 
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#define RD_CONTINUE 7 /* continue execution 

#define RD_KILL 8 /* terminate execution 

#define RD_STEP 9 /**execute one or more instructions*** 
#define RD_READ_GPR 11 /* read general purpose register 
#define RD_READ_FPR 12 /* read floating point register 
#define RD_WRITE_GPR 14 /* write general purpose register 
#define RD_WRITE_FPR 15 /* write floating point register 
#define RD_READ_BLOCK 17 /* read block of data 

#define RD_WRITE_BLOCK 19 /* write block of data 

#define RD_ATTACH 30 /* attach to a process 

#define RD_DETACH 31 /* detach a proc to let it keep running 
#define RD_REGSET 32 /* return entire register set to caller 
#define RD_REATT 33 /* reattach debugger to proc 

#define RD_LDINFO 34 /* return loaded program info 

#define RD_MULTI 35 /* set/clear multi-processing 

#define RD_READ_I_MULT 70 /* Read multiple inst words 

#define RD_READ_GPR_MULT 71 /* Read multiple registers 

#define RD_SINGLE_STEP 100 /**source line single step******xxxaxx 
#define RD_LOAD 101 /* load a task 

#define RD_LOGIN 103 /*ptrace for login 

#define RD_LOGON 103 /*ptrace for logon 

#define RD_LOGOFF 104 /*ptrace for logoff 

#define RD_FILL 105 /*ptrace for fill memory 

#define RD_PASS 106 /*ptrace for pass 

#define RD_SEARCH 107 /*ptrace for search memory 

#define RD_WAIT 108 /*ptrace for wait status information 
/* Added to support ADEPT */ 

#define RD_READ_DCR 110 /*ptrace for reading DCR’s 

#define RD_WRITE_SPR 111 /*ptrace for writing SPR’s 

#define RD_WRITE_DCR 112 /*ptrace for writing DCR’s 

#define RD_STOP_APPL 113 /*ptrace for stopping the application 
#define RD_STATUS 114 /*ptrace for getting run status 
#define RD_READ_SPR 115 /*ptrace for reading SPR’s 

/* Added to support 403GC */ 

#define RD READ _TLB 116 /*ptrace for readingTLB(403GC ) 
#define RD _WRITE_TLB ale? /*ptrace for writing TLB(403GC ) 

/* Added to support 602 */ 

#define RD_READ_SR 118 /*ptrace for reading SR’s 

#define RD_WRITE_SR 119 /*ptrace for writing SR’s 

#define MAX_PTRACE 119 /*last ptrace number 

#define RL_LOAD_REQ 180 /* Remote Loader - Load Request 
#define RL_LDINFO 181 /* Remote Loader - Load Information 
/*TCP/IP services for all sorts of remote debug 

#define OSOPEN_SERVNAME “osopen-dbg” /* OS/Open debug service 

#define OSOPEN_MON_SERVNAME “osopen-mon” /* OS/Open debug monitor svc 
/*new register definition 

#define DAR 1.387 /* Data Address Register (S$dar) 
#define DSISR 138 /* Data St Int Status Reg (Sdsisr) 
#define SRRO 139 /* Save and Restore Register 0 (Ssrr0) 
#define SRR1 140 /* Save and Restore Register 0 (Ssrr1l) 
#define SRO 141 /* Segment Register ($sr0) 

#define SRL 142 /* Segment Register ($sr1l) 
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#define SR2 143 /* Segment Register (S$sr2) * / 
#define SR3 144 /* Segment Register ($sr3) * / 
#define SR4 145 /* Segment Register (S$sr4) * 
#define SR5 146 /* Segment Register ($sr5) * / 
#define SR6 147 /* Segment Register (S$sr6) * / 
#define SR7 148 /* Segment Register ($sr7) * / 
#define SR8 149 /* Segment Register ($sr8) */ 
#define SRY 150 /* Segment Register (S$sr9) */ 
#define SR10 151 /* Segment Register ($sr10) * / 
#define SR11 152 /* Segment Register ($sr11) * / 
#define SR12 153 /* Segment Register (S$sr12) */ 
#define SR13 154 /* Segment Register ($sr13) * / 
#define SR14 155 /* Segment Register (S$sr14) * / 
#define SR15 156 /* Segment Register ($sr15) * / 
#define DEC 157 /* Decrementer ($dec) * / 
#define RTCU 158 /* Real Time Clock Upper (S$rtcu) * / 
#define RTCL 159 /* Real Time Clock Lower ($rtcl) * / 
#define SDRO 160 /* Storage Description Reg (S$sdr0) * / 
#define SDR1 161 /* Storage Description Reg (S$sdr1) * / 
#define EISO 162 /* External Int Summary Regl (Seis1) * / 
#define EIS1 163 /* External Int Summary Reg2(Seis2) * / 
#define EIMO 164 /* External Int Mask Regl (Seim1) * / 
#define EIM1 165 /* External Int Mask Reg2 (Seim2) * / 
#define SRR2 166 /* Save and Restore Register 2 (Ssrr2) */ 
#define SRR3 167 /* Save and Restore Register 3 (Ssrr3) */ 
/*other definitions needed for remote debug *f: 
#define RD_MAXDATA 1800 /* Total no of DWORDS in a MSGDATA * / 
#define RD_MINLENGTH 6 /* Min no of dwords in msg aA 
#define RD_MINBYTES (RD_MINLENGTH*sizeof (unsigned long) ) 

#define RD_MAXBUFFER (RD_MAXDATA - RD_MINLENGTH) 

#define RD_MAXPACKET 1000000 /* Max bytes in TCP/IP packet * / 
#define RD_REGBYTES (32+8) *4 /* No of bytes for all registers a), 
#define NO_KILL 1 /*do not kill any users processes af 
#define KILL_PROC 0 /*kill user process upon logoff */ 
#define MAX ERROR 1014 /*last error for rptrace * / 
#define MIN_ERROR 1000 /*first error for rptrace */ 
#define MIN _PACKET SIZE 24 

#define DBG_SPORT 20044 

#define DBG_DPORT 20050 

/*new error codes a, 
#define RD_NOLOAD_ERR 1000 /*no loader info available wf 
#define RD_COM_ERR 1001 /*communication error occured isis 
#define RD_SIZE_ERR 1002 /*not enough room to pass all info of 
#define RD_NOTSUPP 1003 /*call not supported xf 
#define RD_REG_ERR 1004 /*invalid register number requested if; 
#define RD_NOTAVAIL 1005 /*call not implemented at this time * / 
#define RD_NOFILE_ERR 1006 /*file could not be loaded, no file ay 
#define RD_NOSCAN_ERR 1008 /*could not locate scan string file * / 
#define RD_NOPERM 1010 /*no permission to log on */ 
#define RD_INVALID_ SEQ 1011 /*invalid rptrace sequence */ 
#define RD_BUSY_ERR 1012 /*some users is already logged on ay, 
#define RD_PTRACE_ERR 1014 /*internal ptrace error af 
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#define RD_OK 0 /*rptrace completed ok */: 
#define ARCH_403 0x34000000 /* 403 architecture */ 
#define ARCH_601 0x36000000 /* 601 architecture */ 
#define ARCH_602 0x36303200 /* 602 architecture */ 
#define ARCH_603 0x36303300 /* 603 architecture */ 
#define ARCH_604 0x36303400 /* 604 architecture */ 
typedef struct msgdata /* message data structure */ 
{ unsigned long data_len; /* optional data length } ad 
unsigned long retcode; /* return code }MIN */ 
unsigned long request; /* request type } PART * / 
unsigned long address; /* function parameter }= * / 
unsigned long data [* function parameter }6*DWORD */ 
struct { unsigned f1:1; 


unsigned £2:1; 
unsigned £3:1; 
unsigned padd:21; 
unsigned £25:8; 
} flags; 
#define printmsg flags.f1l 
#define breakpt flags.f2 
#define dbg_seqno flags.f25 
union { unsigned long trace_buffer[RD_MAXBUFFER] ; 
unsigned long processid; 
} parameter; 


#define buffer parameter.trace_buffer /* buffer for data, in any */- 
#define rpid parameter.processid /* process id * / 
} MSGDATA; 

#endif 


A.3 Ptrace Definitions 


The following section presents the application programming interface (API) for rptrace messages. 
One field that is not shown here, because it is common to every call, is the msg.printmsg flag. This 
may be set in an rptrace response where msg.retcode does not equal RD_OK. When the 
msg.printmsg flag is set it indicates that a text string is contained in msg.buffer and that this message 
should be displayed to the user. Typically this is an error message that provides more detail as to why 
the rptrace call failed to return RD_OK. 


Another field that is not shown is the dbg_seqno field. The field provides a mechanism for recovering 
from lost requests and responses. If a request has the dbg_seqno field as not zero, it is compared 
with the value from the previous request. If it matches, the action is not performed and instead, the 
previous response is sent. This allows the debugger to time-out and retry requests without danger of 
performing the same function twice. 


A-4 PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


— Preliminary Copy 


A.3.1_ RD_ATTACH (30) 


Attaches debugger to running process in target environment. 


Request msg.request= RD_ATTACH Requested API function 
msg.rpid= process_id Numeric process ID on the target system.(Any non 
zero value) 
msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 


does not exist 


msg.retcode= EIO (5) One of the parameters is incorrect 


msg.retcode= RD_-COM_ERR (1001) Communication error occurred 


msg.retcode= RD_NOTSUPP (1003) Call not supported for this interface 


msg.retcode= RD_OK (0) Successful completion 


msg.data_len=0 No additional data 
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A.3.2 RD_CONTINUE (7) 


This request causes the process to resume execution. If the dbg_seqno field of the request is zero, 
the response is not returned until the process stops due to a break point or error. Otherwise, an 
immediate response is sent from the RD_CONTINUE request and the debugger should send the 
RD_STATUS request to see if the process has stopped. 


Parameters Description 


Request msg.request= RD_CONTINUE Requested API function 


msg.address= address This field is ignored by ROM monitor 


msg.data= signal 0 


msg.rpid= process_id Numeric process ID on the target system 
msg.data_len= sizeof(msg.rpid) Length of additional data being sent 


Response | msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.data= 0 
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A.3.3 RD_DETACH (31) 


Detaches debugger from running process in target environment. Debugged process is restarted and 
execution continues without debugger control. 


Request 


Parameters 


msg.request= RD_DETACH 


msg.rpid= process_id 


msg.data= 0 


Description 
Requested API function 
Numeric process ID on the target system 


Ignored by ROM monitor 


msg.address=1 


Ignored by ROM monitor 


Response 


msg.data_len= sizeof(msg.rpid) 


msg.retcode= ESRCH (3) 


msg.retcode= RD_COM_ERR (1001) 


Length of additional data being sent 


The msg.pid parameter identifies a process that 
does not exist, or a process that is currently not 
being debugged 


Communications error occurred 


msg.retcode= RD_NOTSUPP (1003) 


Call not supported for this interface 


msg.retcode= RD_OK (0) 


msg.retcode= EIO (5) 


msg.data_len= 0 


Successful completion 
One of the parameters is incorrect 


No additional data is being sent 


Revised 8/22/00 


v. 0.8 


—Preliminary Copy 


A.3.4_ RD_FILL (105) 


Fills memory with zeroes at the location specified by address for the number of bytes specified by 
data. 


Parameters Description 


Request msg.request= RD_FILL Requested API function 


msg.rpid= process_id Numeric process ID on the target system 


msg.address= address Address of memory to fill with zeroes 


msg.data= count Number of bytes to fill with zeroes 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= RD_COM_ERR (1001) Communications error occurred. 
msg.retcode= RD_NOTSUPP (1003) Call not supported for this interface 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= EIO (5) One of the parameters is incorrect 


msg.data_len= 0 No additional data is being sent 
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A.3.5 RD_KILL (8) 


This request causes the process to terminate the same way it would with an exit routine. The ROM 
monitor does not implement this function but simply returns an RD_OK response for compatibility with 
older debuggers. 


Request Requested API function. 
msg.rpid= process_id Process ID of the process to be killed. 
msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 
does not exist 


msg.data_len= 0 Length of additional data being sent 
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Request loader information from target environment. This information is provided to the ROM monitor 
in the boot header or by the RL_LDINFO request. Refer to ROM Monitor Load Format section for 


more information. 


Parameters 


Request msg.request= RD_LDINFO 


msg.rpid= process_id 


Description 
Requested API function 


Process ID from which the loader information is 
requested 


msg.data_len= sizeof(msg.rpid) 


Length of additional data being sent 
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Parameters Description 


Response msg.retcode= RD_- NOLOAD_ERR (1000) | No loader information is available 


msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 
does not exist 

msg.retcode= RD_-COM_ERR (1001) Communication error occurred 

msg.retcode= RD_SIZE_ERR (1002) Not enough room in the buffer to fit all load 
information 

msg.retcode= RD_OK (0) Successful completion 

msg.retcode= EIO (5) One of the parameters is incorrect 

msg.buffer[0]= Idinfo_next Offset to next loader information segment. See 
note below 

msg.buffer[1]= fd File descriptor for loaded object. In remote 


debug OxFFFF FFFF should be returned (this is 
a space filler) 


msg.buffer[2]= textorig Starting text address 


msg.buffer[3]= textsize Size of text 


msg.buffer[4]= dataorig Starting data address. 


msg.buffer[5]= datasize Size of data 


msg.buffer[6]= (char *)pathname Fully qualified filename of the object file. 


msg.buffer[X]= (char *)mnembername Membername (used for shared library objects). 
X does not represent position on word boundary. 
A NULL has to be returned for the membername 
even if the debugged file has no member name 


msg.buffer[Idinfo_next]= Idinfo_next Next loader block (notice "Idinfo_next") 


msg.data_len= "variable" Set to length of data sent in msg.buffer. Data 
length will vary depending on the amount of 
information passed. Remember to count all the 
NULL characters 


Note: dinfo_next=0 indicates that no further loader blocks are present, otherwise Idinfo_next 
contains the offset of the next loader block in the buffer. This is actually the length of 
the current block. For example, if the buffer contains three blocks of lengths 38, 40 and 
41 bytes, the Idinfo_next fields would be 38, 40 and 0, respectively. Note also that the 
blocks do not have to be contiguous - it is possible that the end of one block may not 
directly abut the following block. This may occur if additional information or word- 
aligning padding is placed after the end of the member name string. Pathname and 
membername are strings terminated with a null character. 
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A.3.7 RD_LOAD (101) 


Loads executable program. Full path name of the file to be loaded is passed in this message. The 
ROM monitor will respond by sending an RL_LOAD_REQ to the remote loader daemon port. 


Request msg.request= RD_LOAD Requested API function 


msg.buffer= filename Name of file to load. A NULL character terminates 
filename. filename contains a fully qualified path 
to that file 


msg.data_len= strlen(filename)+1 String length of filename plus NULL character 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= RD_NOFILE_ERR(1006) | Could not locate/load the file 


msg.rpid= process_id Process_id of the newly loaded file. This number 
(integer) can not be equal to -1 (OxFFFF FFFF) or 
0 

msg.data_len= sizeof(msg.rpid) Length of additional data being sent. 
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A.3.8 RD_LOGIN (103) 


Initializes users LOGIN. This request must be the first rptrace request issued by the debugger or 
results will be unpredictable. 


Parameters Description 
Request msg.request= RD_LOGIN Requested API function. 
msg.buffer[0]= host_name This field is ignored by ROM monitor. 
msg.buffer[strlen(host_name)+1]= This field is ignored by ROM monitor. 
user_name 
msg.data_len= Length of additional data being sent 
strlen(host_name)+strlen(user_name)+2 
Response | msg.retcode= RD_COM_ERR (1001) Communication error occurred 
msg.retcode= RD_OK (0) Successful completion 
msg.data_len= 0 Length of additional data being sent 
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A.3.9 RD_LOGOFF (104) 


Performs user LOGOFF function. This is used when the debugger performs normal termination using 
quit or detach. 


Request msg.request= RD_LOGOFF Requested API function 
msg.data= NO_KILL This field is ignored by ROM monitor 


msg.data_len= 0 Length of additional data being sent 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= RD_INVALID_SEQ (1011) | Not logged on. 


msg.data_len= 0 Length of additional data being sent 
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A.3.10 RD READ _D (2) 


This request returns the integer in the debugged process address space at the location pointed to by 
the address parameter. If the value of address is not in a valid address space, unpredictable results 
will occur. 


Parameters Description 


Request msg.request= RD_READ_D Requested API function 


msg.address= address Address of memory to read data from 


msg.rpid= process_id Numeric process ID on the target system 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= EIO (5) Debugged process can not access given address. 


msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 
does not exist 


msg.data= data Data read at location pointed to by address. -1 if 
error 
msg.data_len= 0 Length of additional data being sent 
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A.3.11 RD_READ_FPR (12) 


This request returns the content of one of the floating-point registers. 


Request msg.request= RD_READ_FPR Requested API function 


msg.address= register Name of the register to be read 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 


msg.rpid= process_id Numeric process ID on the target system 


Response msg.retcode= RD_-COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= EIO (5) Register is not defined 


msg.retcode= RD_REG_ERR (1004) Unable to access given register 


occurred 


msg.data= value Value read from register. OXFFFFFFFF if error 


does not exist 


msg.data_len= 0 Length of additional data being sent 
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A.3.12 RD_READ_GPR (11) 


This request returns the content of one of the general-purpose or special-purpose registers of the 
debugged process. Valid registers are defined in "dbog.h" and "sys/reg.h". Not all defined registers are 
supported for all environments. 


Parameters Description 


Request msg.request= RD_READ_GPR Requested API function 


msg.rpid= process_id Numeric process ID on the target system 


msg.address= register Name of the register to be read 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= RD_COM_ERR (1001) Communication error occur 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= EIO (5) Register is not define 


msg.retcode= RD_REG_ERR (1004) Unable to access given register 


msg.data= value Value read from register. OXFFFFFFFF if error 
occurred 
msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 


does not exist 


msg.data_len= 0 Length of additional data being sent 
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A.3.13 RD_READ_GPR_MULT(71) 


This request returns the contents of general-purpose registers 0 to 18, inclusive, of the debugged 
process. 


Parameters Description 


Request msg.request= RD_READ_GPR_MULT | Requested API function 


msg.rpid= process_id Numeric process ID on the target system 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 
msg.retcode= RD_NOTSUPP (1003) Call not supported by this interface 
msg.retcode= RD_REG_ERR (1004) Unable to access given register 


msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 
does not exist 


msg.data_len= 76 (O0x4C) Length of additional data being sent 


msg.buffer[0-18] Values read from GPRO to GPR18. Undefined if 
error 
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A.3.14 RD_READ | (1) 


This request returns the integer in the debugged process address space at the location pointed to by 
the address parameter. If the value of address is not in a valid address space, unpredictable results 
will occur. 


Parameters Description 


Request msg.request= RD_READ_| Requested API function 


msg.address= address Address of memory to read data from 


msg.rpid= process_id Numeric process ID on the target system 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion. 


msg.retcode= EIO (5) Debugged process can not access given address 


msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 
does not exist 


msg.data= data Data read at location pointed to by address. -1 if 
error (retcode should also be set to ElO) 


msg.data_len= 0 Length of additional data being sent 
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Request 


Response 


Parameters 


msg.request= RD_READ_|_ MULT 


msg.address= address 
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Description 


Requested API function 


Address of memory to read data from 


msg.rpid= process_id 


Numeric process ID on the target system 


msg.data_len= sizeof(msg.rpid) 
msg.retcode= RD_COM_ERR (1001) 
msg.retcode= RD_OK (0) 


Length of additional data being sent 
Communication error occurred 


Successful completion 


msg.retcode= EIO (5) 


Debugged process can not access given address 


msg.retcode= ESRCH (3) 


msg.retcode= RD_NOTSUPP (1003) 
msg.buffer[0-0x1 F] 


The msg.pid parameter identifies a process that 
does not exist 


Call not supported by this interface 


Contents of addresses from location pointed to by 
address to address + Ox1F 


msg.data_len= 128 (0x80) 


Length of additional data being sent 
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A.3.16 RD_READ_SPR (115) 


This request reads data directly from one of the SPRs (not the process's copy). All SPR registers are 
accessible through this message request. The sender is responsible for supplying valid SPR values, 
no error checking is performed on this field. 


Request msg.request= RD_READ_ SPR Requested API function 


msg.address= SPR number SPR number to read 


msg.data_len= 0 Length of additional data being sent 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 
msg.data= value Value read from register 
msg.data_len= 0 Length of additional data being sent 
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A.3.17 RD_READ SR (118) 


This request returns the content of one of the segment registers. 


Request msg.request= RD_READ_SR Requested API function 


msg.address= register Name of the register to be read 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 


msg.rpid= process_id Numeric process ID on the target system 


Response msg.retcode= RD_-COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= EIO (5) Register is not defined 


msg.retcode= RD_REG_ERR (1004) Unable to access given register 


occurred 


msg.data= value Value read from register. OXFFFFFFFF if error 


does not exist 


msg.data_len= 0 Length of additional data being sent 
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A.3.18 RD_STATUS (114) 


This request is used to get program execution status and to determine if a previous RD_CONTINUE 
request was received. 


Request msg.request= RD_STATUS Requested API function 


msg.rpid= process_id Numeric process ID on the target system 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 


Response | msg.address= execution status Status is 1 if program is running and 0 if stopped. 
In the case of an error, this field will be -1 
(OxFFFFFFFF) 


msg.data= sequence number Sequence number of the last RD_CONTINUE 
request that was received 


msg.retcode= RD_-COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 
msg.retcode= RD_ESRCH (3) The msg.pid field identifies a process that does not 
exist 


Revised 8/22/00 v. 0.8 A-23 


A.3.19 RD_STOP_APPL (113) 


This request is used to interrupt program execution. 


—Preliminary Copy 


Request msg.request= RD_STOP_APPL Requested API function 
msg.rpid= process_id Numeric process ID on the target system 
msg.data_len= sizeof(msg.rpid) Length of additional data being sent 

Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 
msg.retcode= RD_OK (0) Successful completion 
msg.retcode= RD_ESRCH (3) The msg.pid field identifies a process that does not 

exist 
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A.3.20 RD_WAIT (108) 


This call allows the debugger to determine the current status of the debugged process after it is 
stopped. The first (least significant) byte of the process status indicates the reason for stoppage: this 
is always 0x7f. The second byte contains the signal number that caused the stop. Valid signals are: 

* AIX_SIGILL (4) - illegal instruction 

¢ AIX_SIGTRAP (5) - hit a trap instruction (breakpoint) 

¢ AIX_SIGFPE (8) - floating point error 

* AIX_SIGSEGV (11) - storage violation 

For example after hitting a breakpoint, the status of 0x57f is returned to the debugger. After the 


program terminates, the first byte contains 0x00 and the rest of the status holds the program exit 
code. After RD_KILL call wait status of 0x57f should be returned. 


Parameters Description 
Request msg.request= RD_WAIT Requested API function 


msg.data_len= 0 Length of data in msg.buffer 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 
msg.data= status Process status 


msg.address= pid Process id 


msg.data_len= strlen(message_string) | The ROM monitor always returns 0 in this field 


msg.buffer= message_string Formatted message string text (NULL terminated) 


Revised 8/22/00 v. 0.8 A-25 


—Preliminary Copy 


A.3.21 RD_WRITE_BLOCK (19) 


This request writes a block of data into the address space of the debugged process at the address 
pointed to by the msg.address field. The number of bytes to write is contained in the msg.data field 
and the data is in the msg.buffer field. Unpredictable results occur if the msg.address parameter 
points to a location that can not be accessed by the debugged process. 


Parameters Description 
Request msg.request= RD_WRITE_BLOCK Requested API function 


msg.address= address Address of memory to write data to 


msg.data= count Number of bytes of buffer area to be written 


msg.buffer Data to be written 


msg.data_len= count Length of additional data being sent 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred. 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= EIO (5) Debugged process can not access given address. 


msg.data_len= 0 Length of additional data being sent 
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A.3.22 RD_WRITE_D (5) 


This request writes the value of the msg.data parameter into the address space of the debugged 
process at the address pointed to by the msg.address parameter. Unpredictable results occur if the 
msg.address parameter points to a location that can not be accessed by the debugged process. 


Request 


Parameters 


msg.request= RD_WRITE_D 


msg.address= address 


Description 


Requested API function. 


Address of memory to write data to 


msg.data= data 


Data to write to memory. 


Response 


msg.rpid= process_id 
msg.data_len= sizeof(msg.rpid) 


msg.retcode= RD_COM_ERR (1001) 


Numeric process ID on the target system 
Length of additional data being sent 


Communication error occurred 


msg.retcode= RD_OK (0) 


Successful completion 


msg.retcode= EIO (5) 
msg.retcode= ESRCH (3) 


msg.data= data 


Debugged process can not access given address 


The msg.pid parameter identifies a process that 
does not exist. 


Data written at location pointed to by address. -1 if 
error (retcode should also be set to ElO or 
ESRCH). 


msg.data_len= 0 


Length of additional data being sent 
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This request writes data to one of the floating-point registers: 


Parameters 


Description 


Request msg.request= RD_WRITE_FPR Requested API function 
msg.rpid= process_id Numeric process ID on the target system 
Name of the register to be written 
msg.data= value Value to be written to the register 
msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= RD_-COM_ERR (1001) Communication error occurred 
Successful completion 
msg.retcode= EIO (5) Register is not defined 
msg.retcode= RD_REG_ERR (1004) Unable to access given register 
msg.data= value Value written to register. OXFFFFFFFF if error 
occurred 
The msg.pid parameter identifies a process that 
does not exist 
msg.retcode= RD_-COM_ERR (1001) Communication error occurred 
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A.3.24 RD_WRITE_GPR (14) 


This request writes data to one of the general-purpose or special-purpose registers of the debugged 
process. Valid registers are defined in dbg.h and sys/reg.h. Not all defined registers are supported for 
all environments. 


Parameters Description 


Request msg.request= RD_WRITE_GPR Requested API function 


msg.rpid= process_id Numeric process ID on the target system 


msg.address= register Name of the register to be written 


msg.data= value Value to be written to the register 
msg.data_len= sizeof(msg.rpid) Length of additional data being sent 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred. 


msg.retcode= RD_OK (0) Successful completion 


msg.retcode= EIO (5) Register is not defined 

msg.retcode= RD_REG_ERR (1004) Unable to access given register 

msg.data= value Value written to register. OXFFFFFFFF if error 
occurred 

msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 


does not exist 


msg.data_len= 0 Length of additional data being sent 
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A.3.25 RD_WRITE_I (4) 


This request writes the value of the msg.data parameter into the address space of the debugged 
process at the address pointed to by the msg.address parameter. This request fails if the 
msg.address parameter points to a location that can not be accessed by debugged process. This call 
sets break points in the debugged process by writing TRAP (0x7D821008) instructions. 


Parameters Description 
Request msg.request= RD_WRITE_| Requested API function 


msg.rpid= process_id Numeric process ID on the target system 


msg.address= address Address of memory to write data to 


msg.data= data Data to write to memory 


msg.data_len= sizeof(msg.rpid) Length of additional data being sent 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 

msg.retcode= EIO (5) Debugged process can not access given address 

msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 
does not exist. 

msg.data= data Data written at location pointed to by address. -1 if 
error (retcode should also be set to ElO or 
ESRCH) 

msg.data_len= 0 Length of additional data being sent 
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A.3.26 RD_WRITE_SPR (112) 


This request writes data directly to one of the SPRs (not the process's copy). All SPR registers are 
accessible through this request. The requester is responsible for supplying valid SPR values. No error 
checking is performed on this field. 


Request 


Response 


msg.request= RD_WRITE_SPR Requested API function 


msg.address= SPR number SPR number to be written 


msg.data= value Data to write to register 


msg.data_len= 0 Length of additional data being sent 


msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.data_len= 0 Length of additional data being sent 
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This request writes data to one of the segment registers. 


Parameters 


Description 


Request msg.request= RD_WRITE_SR Requested API function 
msg.rpid= process_id Numeric process ID on the target system 
Name of the register to be written 
msg.data= value Value to be written to the register 
msg.data_len= sizeof(msg.rpid) Length of additional data being sent 
Response msg.retcode= RD_-COM_ERR (1001) Communication error occurred 
Successful completion 
msg.retcode= EIO (5) Register is not defined 
msg.retcode= RD_REG_ERR (1004) Unable to access given register 
msg.data= value Value written to register. OXFFFFFFFF if error 
occurred 
msg.retcode= ESRCH (3) The msg.pid parameter identifies a process that 
does not exist 
msg.data_len= 0 Length of additional data being sent 
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A.3.28 RL_LDINFO (181) 


This request provides load information from the host to the ROM monitor. This request is used when 
the target is loaded by a process other than the debugger. The information specified on the this 
request will be returned on subsequent RD_LDINFO requests. 


Request msg.request= RL_LDINFO Requested API function 


msg.data_len= sizeof(struct Idinfo) + Length of additional data being sent 
strlen(pathname) 


msg.buffer= load information See description of RD_LDINFO request 


Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) Successful completion 


msg.data_len= 0 Length of additional data being sent 
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This request flows from the ROM monitor to the host when a RD_LOAD request is received. The port 
of the request is for the remote loader daemon (20050) to accommodate loading by a process 


independent from the debugger. 


Request Requested API function 
msg.buffer= filename NULL terminated string containing fully qualified 
name of file to be loaded 
msg.data_len= strlen(filename) Length of additional data being sent 
ee ee 
Response msg.retcode= RD_COM_ERR (1001) Communication error occurred 


msg.retcode= RD_OK (0) 


Successful completion 


msg.retcode= RD_NOFILE_ERR 
(1006) 


msg.retcode= RD_PTRACE_ERR 
(1014) 


msg.rpid= process_id 


Can't open file or file is incorrect format 


Error reading file 


Process ID of newly loaded file. This number 
(integer) can not be equal to -1 (OxFFFF FFFF) or 
0 


msg.data_len= sizeof(msg.rpid) 


Length of additional data being sent 
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Appendix B. ROM Monitor Load Format 


This appendix presents the ROM Monitor load format requirements. 


B.1 Overview 


The ROM Monitor load format is designed to permit the specification of multiple text and data 
sections. The format consists of a linked list of sections of specified types prefixed by a small boot 
header, boot_block, that specifies the initial target of the image and the entry point. The boot_block 
header is placed at the front of the image by eimgbld or nimgbld. The ROM Monitor does no 
relocation. It is assumed that the destination addresses for the individual sections are the same ones 
specified during the application’s linkage. The info_block structure is reserved in the bootstrap 
program, bootlLib.s. eimgbld or nimgbld patch in the values within the info_block structure for 
bootLib to use at run time. The bootstrap program processes the sections back to front, that is, from 
the end of the image to the beginning. This is to avoid destructive overlap during the processing of 
typical images. 


The sections are preceded by header blocks which identify the section types. The headers are linked 
together in a doubly linked list. 


B.2 Section Types 


There are three basic section types. Generally, they can occur in the image in any order, but are 
usually arranged in ascending address order. The section header block has the following format: 


[OR ee + 
| Relocation block structure. 
Se ree */ 
typedef struct rel_block { 

unsigned long type; 

unsigned long dest_addr; 

unsigned long size; 

union { 


struct data_info { 
unsigned long size_to_fill; 
unsigned long char_to_fill; 
} data_info_str; 
struct text_info { 
unsigned long toc_pointer; /* used for XCOFF; not used for ELF */ 
unsigned long entry_pt; 
} text_info_str; 
unsigned long number_symbols; 
} section_info; 
struct rel_block *next,; 
struct rel_block *bptr; 
} rel_block_t; 


Revised 8/22/00 v. 0.8 B-1 


—Preliminary Copy 


The type field is one of the following manifest constants: 


#define TEXT_SECT 0x00000001 
#define DATA_SECT 0x00000002 
#define SYMB_SECT 0x00000004 


The dest_addr specifies the target for the block, while size is the extent of the block, not counting the 
header. The bootstrap program uses this information to move the block to the destination specified at 
link time. next and bptr are the section header forward and backward pointers, respectively. 


B.2.1 First Section 


The first section is a text section. The ROM loader places the entire image at the address specified in 
the boot_block header. The entry point specified in the boot_block header is assumed to be a branch, 
followed by the first section header, info_block. This is to allow the bootstrap to easily gain immediate 
addressability to the first section block. 


The format of the first section block is shown below: 


[OR a a a ss re + 
| First section header 
a */ 
struct info_block { 
long magic_num; /* magic number */ 
long text_start; /* addr of text section from section header */ 
long text_size; /* size of text section from section header 
*/ 
long data_start; /* addr of data section from section header */ 
long data_size; /* size of data section from section header */ 
long elf_hdr_size; /* size of ELF headr */ 
long sym_start; /* addr of symbol table */ 
long num_syms; /* number of symbols */ 
long toc_ptr; /* used for XCOFF; not used for ELF */ 
struct rel_block * next; /* pointer to next boot section header 
*/ 


}; 

magic_num is used for verification purposes and must be X’004D 5054’. 

text_start is the physical address value from the object text header. 

text_size is the size in bytes from the object text header. 

data_start is the physical address from the object data header. 

data_size is the size in bytes from the object data header. 

elf_hdr_size is the size of the object header. The debugger requires this information. 
sym_start is the address of the symbol table in storage. 

num_syms is the number of symbol entries. 


next points to the next section header. 


B.2.2 Text Section 


For a text section, the union section_info contains the structure text_info, specifying the entry point 
of the text section. 


B-2 PPC405GP Reference Design Kit User’s Manual v. 0.8 Revised 8/22/00 


— Preliminary Copy 


B.2.3 Data Section 


For a data section, the union section_info contain the structure data_info, specifying size_to_fill 
and char_to_fill. These parameters are used to optionally fill a region past the size extent specified in 
the base rel_block with a character. It is most often used to zero bss by specifying the size of the bss 
in size_to_fill and 0x0 for char_to_fill. 


B.2.4 Symbol Section 


For symbols, the union section_info contains the number of symbols in the section. The data in this 
section consists of the symbol table from the original object file. 


B.3 Boot Header 


The entire image is preceded by the boot header that was added by nimgbld or eimgbld. The ROM 
loader uses this information to verify that it is a ROM Monitor load image, determine where to place 
the image, and whether to invoke the ROM Monitor debugger before transferring control to the entry 
point. The boot header is stripped off by the ROM Monitor loader and does not appear at the load 
address. 


The boot header has the following format: 


[OR ee + 
| Boot header. 
sa */ 
typedef struct boot_block { 

unsigned long magic; 

unsigned long dest; 

unsigned long num_512blocks; 

unsigned long debug_flag; 

unsigned long entry_point; 

unsigned long reserved[3]; 


} boot_block_t; 


magic identifies this image as a legitimate ROM Monitor image and must have the value 
X’0052 504F’. 


dest is the target address for the image (after the boot header is stripped off). 


num_512blocks - Boot images are padded to a multiple of 512 byte blocks. This field specifies the 
number of blocks. 


debug_flag controls whether the ROM Monitor debugger gets control before the loaded image starts. 
If the value is 0x0, the image runs immediately. If 0x01, the debugger gains control as soon as the 
load is complete. 


entry_point specifies the address where the image will receive control. 
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ppclsync() function 10-68 
ppcMfccr0() function 10-69 
ppcMfcpc0_cr0() function 10-70 
ppcMfcpc0_cri() function 10-71 


ppcMfdac1() - ppcMfdac2() function 10-72 
ppcMfdbcr0() - ppcMfdbcr1() function 10-73 
ppcMfdbsr() function 10-74 

ppcMfdccr() function 10-75 


ppcMfdcp0_addr0() - ppcMfkaddr3() function 10-76 
ppcMfdcp0_cfg() function 10-77 

ppcMfdcp0_esr() function 10-78 

ppcMfdcp0_id() function 10-79 

ppcMfdcp0_itor0() - ppcMfdcp0_itor3() function 10-80 
ppcMfdcp0_membear() function 10-81 
ppcMfdcp0_plbbear() function 10-82 
ppcMfdcp0O_ram() function 10-83 

ppcMfdcp0_ver() function 10-84 

ppcMfdewr() function 10-85 

ppcMfdear() function 10-86 

ppcMfdma0_cr0() - ppcMfdma0_cr3() function 10-87 
ppcMfdma0_ct0() - pocMfdma0_ct3() function 10-88 
ppcMfdma0_da0() - ppcMfdma0_da3() function 10-89 
ppcMfdma0_sa0() - ppcMfdma0_sa3() function 10-90 
ppcMfdma0_sg0() - ppcMfdma0_sg3() function 10-91 
ppcMfdma0_sgc() function 10-92 

ppcMfdma0_sr() function 10-93 

ppcMfdvc1() - ppcMfdvc2() function 10-94 
ppcMfesr() function 10-95 

ppcMfevpr() function 10-96 

ppcMfgpr1() function 10-97 

ppcMfgpr2() function 10-98 

ppcMfiac1() - ppcMfiac4() function 10-99 
ppcMficcr() function 10-100 

ppcMficdbdr() function 10-101 

ppcMfmalO_cfg() function 10-102 

ppcMfmal0_esr() function 10-103 

ppcMfmal0_ier() function 10-104 
ppcMfmalO_rcbs0() function 10-105 
ppcMfmal0_rxcarr() function 10-106 
ppcMfmal0_rxcasr() function 10-107 
ppcMfmal0_rxctpOr() function 10-108 
ppcMfmal0_rxdeir() function 10-109 
ppcMfmal0_rxeobisr() function 10-110 
ppcMfmal0_txcarr() function 10-111 
ppcMfmal0_txcasr() function 10-112 
ppcMfmal0_txctpOr() function 10-113 
ppcMfmal0_txctpir() function 10-114 
ppcMfmal0_txdeir() function 10-115 
ppcMfmal0_txeobisr() function 10-116 

ppcMfmpmit() function 10-117 

ppcMfmsr() function 10-118 
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10-119 
10-120 

10-121 

10-122 


ppcMfocm0_dsarc() function 
ppcMfocm0_dsentl() function 
ppcMfocm0_isarc() function 
ppcMfocm0_iscntl() function 
ppcMfpid() function 10-123 
ppcMfpit() function 10-124 
ppcMfpvr() function 10-125 
ppcMfsdram0_bOcr() - ppcMfsdram0_b3cr() function 10- 
126 
ppcMfsdram0_bear() function 10-127 
ppcMfsdram0_besr0() - ppcMfsdram0_besr1() function 
10-128 
ppcMfsdram0_cfg() function 
ppcMfsdram0_ecccfg() function 10-130 
ppcMfsdram0_eccesr() function 10-131 
ppcMfsdram0_rtr() function 10-132 
ppcMfsdram0_tr() function 10-133 
ppcMfsgr() function 10-134 
ppcMfsler() function 10-135 
ppcMfsprg0() - ppcMfsprg7() function 
ppcMfsrr0() function 10-137 
ppcMfsrri() function 10-138 
ppcMfsrr2() function 10-139 
ppcMfsrr3() function 10-140 
ppcMfsuOr() function 10-141 
ppcMftb() function 10-142 
ppcMftcr() function 10-143 
ppcMitsr() function 10-144 
ppcMfuicO_cr() function 10-145 
ppcMfuicO_er() function 10-146 
ppcMfuicO_msr() function 10-147 
ppcMfuicO_pr() function 10-148 
ppcMfuicO_sr() function 10-149 
ppcMfuicO_tr() function 10-150 
ppcMfuicO_vr() function 10-151 
ppcMfzpr() function 10-152 
ppcMiccr0() function 10-153 
ppcMicpc0_cr0() function 10-154 
ppcMtcpcO_cri() function 10-155 
ppcMidact1() - ppcMtdac2() function 
ppcMidbcr0() - ppcMtdbcr1() function 
ppcMidbsr() function 10-158 
ppcMidccr() function 10-159 
ppcMtdcpO_addr0() - ppcMtdcpO_addr1() function 
160 
ppcMtdcp0_cfg() function 10-161 
ppcMtdcp0_esr() function 10-162 
ppcMtdcp0_itor0() - ppocMtdcp0_itor3() function 
ppcMtdcp0O_ram() function 10-164 
ppcMidewr() function 10-165 
ppcMidear() function 10-166 
ppcMtdma0_cr0() - ppcMtdma0_cr3\() functions 
ppcMtdma0_ct0() - ppcMtdma0_ct3() functions 
ppcMtdma0_da0() - ppcMtdmada() functions 
ppcMtdma0_sa0() - ppcMtdma0_sa3() functions 
ppcMtdma0_sg0() - ppcMtdma0_sg3() functions 
ppcMtdma0_sgc() function 10-172 
ppcMtdma0_sr() function 10-173 
ppcMtdvc1() - ppcMtdvc2() function 
ppcMtesr() function 10-175 
ppcMtevpr() function 10-176 


10-129 


10-136 


10-156 
10-157 
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10-163 


10-167 
10-168 
10-169 
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10-174 
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ppcMtiac1 () - 10-177 
ppcMticcr() function 
ppcMtmal0_cfg() function 
ppcMtmal0_esr() function 
ppcMtmal0_ier() function 
ppcMitmal0_rcbs0() function 
ppcMtmal0_rxcarr() function 
ppcMtmal0_rxcasr() function 
ppcMtmal0_rxctpOr() function 
ppcMtmal0_rxdeir() function 
ppcMtmal0_rxeobisr() function 
ppcMtmal0_txcarr() function 
ppcMtmal0_txcasr() function 
ppcMtmal0_txctpOr() function 
ppcMtmal0_txctpir() function 
ppcMtmal0_txdeir() function 
ppcMimal0_txeobisr() function 
ppcMimpmit() function 10-194 
ppcMimsr() function 10-195 
ppcMtocm0_dsarc() function 
ppcMtocm0_dscntl() function 
ppcMtocm0_isarc() function 
ppcMtocm0_iscntl() function 
ppcMipid() function 10-200 
ppcMipit() function 10-201 
ppcMtsdram0_bOcr() - ppcMtsdram0_b8cr() function 
202 
ppcMtsdram0_bear() function 10-203 
ppcMtsdram0_besr0() - ppcMltbesrb() 
ppcMisdram0_cfg() function 10-205 
ppcMtsdram0_ecccfg() function 10-206 
ppcMtsdram0_eccesr() function 10-207 
ppcMtsdram0_rtr() function 10-208 
ppcMtsdram0_tr() function 10-209 
ppcMisgr() function 10-210 
ppcMisler() function 10-211 
ppcMtsprg0() - pocMtsprg7() function 
ppcMisrr0() function 10-213 
ppcMisrr1() function 10-214 
ppcMisrr2() function 10-215 
ppcMisrr3() function 10-216 
ppcMtsu0r() function 10-217 
ppcMitb() function 10-218 
ppcMitcr() function 10-219 
ppcMitsr() function 10-220 
ppcMtuicO_cr() function 10-221 
ppcMtuicO_er() function 10-222 
ppcMtuicO_pr() function 10-223 
ppcMtuicO_sr() function 10-224 
ppcMtuicO_tr() function 10-225 
ppcMtuicO_ver() function 10-226 
ppcMizpr() function 10-227 
ppcOrMsr() function 10-228 
ppcSync() function 10-229 
ptrace 
definitions A-4 

RD_ATTACH A-5 

RD_CONTINUE A-6 

RD_DETACH A-7 

RD_FILL A-8 

RD_KILL A-9 


ppcMtiac4() function 
10-178 
10-179 
10-180 
10-181 
10-182 
10-183 
10-184 
10-185 
10-186 
10-187 
10-188 
10-189 
10-190 
10-191 
10-192 
10-193 


10-196 

10-197 
10-198 
10-199 


10-204 


10-212 


Index 
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RD_LDINFO A-10 
RD_LOAD A-12 

RD LOGIN A-13 

RD LOGOFF A-14 
RD_READ D A-15 
RD_READ FPR A-16 
RD_READ GPR A-17 
RD_READ_GPR_MULT A-18 
RD_READ_| A-19 
RD_READ | MULT A-20 
RD_READ SPR A-21 
RD_READ SR A-22 

RD STATUS A-23 
RD_STOP_APPL A-24 
RD_WAIT A-25 
RD_WRITE_BLOCK A-26 
RD_WRITE_D A-27 
RD_WRITE_FPR A-28 
RD_WRITE_GPR A-29 
RD_WRITE_! A-30 
RD_WRITE_SPR_ A-31 
RD_WRITE_SR A-32 
RL_LDINFO A-33 
RL_LOAD_REQ A-34 


Q 
Queue Library 9-2 


R 

RAM Disk Library 9-2 

Rate Monotonic Scheduling (RMS) Library 9-2 
RD_ATTACH definition A-5 
RD_CONTINUE definition A-6 
RD_DETACH definition A-7 
RD_FILL definition A-8 

RD_INFO definition A-10 

RD_KILL definition A-9 

RD_LOAD definition A-12 
RD_LOGIN definition A-13 
RD_LOGOFF definition A-14 
RD_READ _D definition A-15 
RD_READ_FPR definition A-16 
RD_READ_GPR definition A-17 
RD_READ_GPR_MULT definition A-18 
RD_READ I definition A-19 
RD_READ_|_ MULTI definition A-20 
RD_READ_SPR definition A-21 
RD_READ_SR definiton A-22 
RD_STATUS definition A-23 
RD_STOP_APPL definition A-24 
RD_WAIT definition A-25 
RD_WRITE_BLOCK definition A-26 
RD_WRITE_D definition A-27 
RD_WRITE_FPR definition A-28 
RD_WRITE_GPR definition A-29 
RD_WRITE_| definition A-30 
RD_WRITE_SPR definition A-31 
RD_WRITE_SR definition A-32 
read from keyboard port 9-13 
Real_time Executive 9-3 

Real-time Clock Interface Support Library 9-5 
Recursion, see Recursion 


Remote Source Level Debug Library 9-2 
Ring Buffer Library 9-2 
RL_LDINFO definition A-33 
RL_LOAD_REQ definition A-34 
ROM monitor 
accessing 7-6 
bootp and tftp configuration 7-2 
PC 7-2 
RS/6000 7-5 
SUN 7-4 
communication features 7-2 
menus 7-7 
cache options 7-25 
changing IP addresses 7-12 
disabling the automatic display 7-17 
displaying the current configuration 7-18 
entering the debugger 7-15 
exiting the main menu 7-23 
initial ROM monitor menu 7-8 
saving the current configuration 7-19 
selecting boot devices 7-10 
selecting power-on tests 7-9 
using the ping test 7-13 
source code 7-1 
user functions 7-25 
ROM monitor load format 
boot header B-3 
section types B-1 
data section B-3 
first section B-2 
symbol section B-3 
sections types 
text section B-2 
RPC Support Library 9-2 
RS/6000 host configuration 4-5 
ethernet setup 4-7 
serial portsetup 4-5 
services file 4-9 
RS/6000 software installation 3-7 
board support package 3-7 
High C/C++ compiler 3-9 
RISCWatch debugger 3-10 
rtx.o library 9-3 
rtxLib.a library 9-3 
Runtime Library 9-2 


Ss 
sidbprintf() function 10-230 
s2dbprintf() function 10-232 
sample applications 
overview 8-1 
resolving problems 8-9 
bootp and tftp servers 8-10 
using the ping test 8-10 
ROM monitor flash image 8-1 
using 8-4 
Dhrystone benchmark 8-4 
MAC sample program 8-7 
timesamp program 8-6 
usr_samp program 8-5 
SCSI Support Library 9-2 
Serial Port Support Library 9-4 
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Serial Support Library 9-2 
set_time_once_only() function 8-7 
software components 1-1 
board support software 1-1 
HIGH C/C++ compiler 1-3 
RISCWatch debugger 1-3 
Software Timer Tick Support Library 9-5 
Sun host configuration 4-3 
ethernet setup 4-4 
serial portsetup 4-4 
services file 4-4 
Sun software installation 3-3 
board support package 3-3 
High C/C++ compiler 3-5 
RISCWatch debugger 3-7 
Symbol Support Library 9-2 


T 
TCP/IP Protocol Support Library 9-2 
Telnet Client Support Library 9-3 
Telnet Daemon Support Library 9-3 
terminal emulator 6-3 

PC terminal emulation 6-3 

RS/6000 terminal emulation 6-5 

Sun terminal emulation 6-4 
tickLib.a library 9-5 
time, setting on on-board clock 8-7 
timebase_speed() function 10-233 
Timer Tick Support 9-3 
timertick_install() function 10-234 
timertick_remove() function 10-235 
tools 9-26 

eimgbld 9-30 

elf2rom 9-26 

hbranch 9-28 
Trivial File Transfer Protocol Library 9-3 
TTY Support Library 9-3 


V 

VGA device driver 9-16 

VGA library 9-3 

vga_cls() function 10-236 

vga_fill_block() function 10-237 
vga_get_cursor_info() function 10-238 
vga_get_screen_dimensions() function 10-239 
vga_get_vid_mem_start() function 10-240 
vga_init() function 10-241 

vga_print_char() function 10-242 
vga_print_char_at_cursor() function 10-243 
vga_print_string() function 10-244 
vga_print_string_at_cursor() function 10-245 
vga_scroll_up() function 10-246 
vga_set_cursor_info() function 10-247 
vga_set_mode() function 10-248 
vga_set_pixel() function 10-249 
vga_write_data() function 10-250 
vgadd_init() function 10-251 

vsidbprintf() function 10-252 
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